Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-02/vdl020d.zip/VGEN.DOC

Text File | 1993-04-14 | 134KB | 6,752 lines

{
════════════════════════════════════════════════════════════════════════════

 Visionix General Functions Unit (VGEN)
 Copyright 1991,92,93 Visionix
 ALL RIGHTS RESERVED

────────────────────────────────────────────────────────────────────────────

 Revision history in reverse chronological order:

 Initials  Date      Comment
 --------  --------  -------------------------------------------------------

 mep       04/04/93  Now Sort works with ShortInt, Byte, Integer, Word,
                     LongInt, String, PString, Real, and "User-supplied"
                     arrays (ie. Records).

 mep       03/29/93  Now uses TDecHex in VTypes.
                     Renamed PurgeTypeAheadBuffer to PurgeKbdBuf.

 mep       03/26/93  Now works with VBios.

 lpg       03/12/93  Completed Source Code Commenting

 lpg       03/11/93  Fixed Bug in BinToChar, IsHexByte
                     Added: HexToDecStr
                     Modified: DecToHexStr

 lpg       03/11/93  Added Source Commenting

 jrt       03/08/93  Moved DOS functions into unit VDOSHIGH

 jrt       02/15/93  Documentation integration and misc changes.
                       Renamed FirstString --> ProperString

 mep       02/11/93  Cleaned up code for beta release
                     Fixed SetKeyRate and DisketteStatus for DPMI mode.

 jrt       2/08/93   Sync with Beta 0.12

 mep       2/02/93   Added: DecToHexStr

 mep       1/31/93   Added: FileCRC32, CRC32String, FileCRC16,
                       and CRC16String.
                     Changed CRC32 to CRC32Char and CRC32Buffer.
                     Changed CRC16 to CRC16Char and CRC16Buffer.

 lpg       1/12/92   Modified: Trim
                     Added: TrimChar
                     Updated: DisketteStatus

 mep       1/2/93    Fixed: DeleteChars, UpperString, FirstString, PosCount,
                       StrToAsciiZ, AsciiZtoStr, Sort, PurgeTypeAheadBuffer.
                     Added: FillWord, KeyboardOff, KeyboardOn.

 lpg       12/27/92  Cleaned up unnecessary Code

 mep       12/22/92  Fixed PosNext, PosNextDelimit - TP70 bug.
                     Added: UnPutDot, PosAfter and PosBefore.

 mep       12/19/92  Fixed AddCommas.

 mep       12/16/92  Fixed FileExist only include file types
                       (not Directory and VolumeID).
                     Added: AddCommas.

 jrt       12/15/92  Changes for bp 7.0:
                       Added code to linear<-->ptr functions to support
                       pascal 7.0; changed PurgeTypeAheadBuffer to use
                       Seg0040 constant instead of direct value.

 mep       12/09/92  Fixed InDir, PutSlash, FileExist, GetFileTime,
                       GetFileSize, DirEmpty.
                     Added: TakeWord, TakeQuote, UnPutSlash, and MkSubDir.

 mep       12/08/92  Fixed CRC32 to work correctly.
                     Added credits at end of unit.

 jrt       12/07/92  Sync with beta 0.11 release

 mep       12/06/92  Made CompareSmaller assembly.
                     Fixed Sort, PutSlash, SwapBuffers.
                     Added: CopyOverStr, PosCount;

 jrt       12/02/92  Added: PtrToLin, LinToPtr, Ptr math functions,
                       NewString and DisposeString.

 mep       12/01/92  Added: CopyStr, PutSlash, PutDot, FileExist, GetFileTime,
                       GetFileAttr, GetFileSize, DirExist, DirEmpty,
                       PredDir, InDir, MaskWildcards

 mep       11/30/92  Sync update. Beta 0.10

 mep       11/29/92  Sync update.
                     Changed: SwapBuffers, Compare, CompareSmaller

 lpg       11/28/92  Added: DecToBCD, BCDtoDec, ByteToBCD, BCDtoByte,
                       WordToBCD, BCDtoWord, GetDOSVersion, DisketteStatus,
                       and FloppyReady.

 mep       11/25/92  Overlooked code and updated few bugs.
                     Cleaned-up code.
                     Re-implemented FastCompare.

 jrt       11/21/92  Sync with beta 0.08

 lpg       11/19/92  Corrected LowerChar, ArrayZtoStr, StrToArrayZ

 lpg       11/19/92  Added: ByteToBin, IntToBin, WordToBin, LongToBin,
                       BinToChar, BinToByte, BinToInt, BinToWord, BinToLong

 jrt       11/18/92  Got rid of swapNoBuff functions; set greater/lesser
                       code back to pascal on funcs that deal with signed
                       values

 jrt       11/11/92  Converted Swap funcs and Greater/lesser funcs to
                       asm code for performance.

 lpg       11/10/92  Added ValidByte, ValidInt, ValidLong, ValidFloat,
                       ValidSci, ValidHexByte, ValidHexWord, ValidHex.

 mep       11/06/92  Changed PosNextField to return SubS if '=' not found.

 lpg       11/01/92  Added Dollar Conversion Functions

 lpg       10/19/92  Moved Date/Time functions to VDATES

 lpg       10/18/92  Added IncTime, DecTime, IncDate, DecDate, IncDateTime,
                       DecDateTime, AddTime, SubTime, AddDate, SubDate,
                       AddDateTime, SubDateTime, SoundexPack, SoundexUnPack

 lpg       10/08/92  Added MarkTime, Modified ClockOn/Off to use MarkTime
                       SwapByteNoBuff, SwapIntNoBuff, SwapWordNoBuff,
                       PosNextDelimit

 mep       10/06/92  Fixed Sort for ANY type.
                     Removed CompareBytes - now use CompareBuffers.
                     Removed FastCompare - now use Compare
                     Updated SwapBuffers.

 mep       10/03/92  Added NEW functions:
                       GetCurrDateTime, DateTimeOK, DateTimeStr, StrDateTime,
                       DateTimeLinear, LinearDateTime, PosNext, PosNextField,
                       PosNextData, Compare, SetKeyRate, SetKeyFast,
                       FirstString, PurgeTypeAheadBuffer,
                       CRC16, CRC32, Sort, SwapBuffers, CompareBuffers.

                     Organization of code.

                     Changed functions:
                       StrToArray, StrToArrayZ, ArrayZtoStr

 lpg       10/01/92  Added More Functions.

 jrt       09/01/92  First logged revision.

════════════════════════════════════════════════════════════════════════════

NOT DONE:

  Function DecToHexStr(                S         : STRING   ) : STRING;

}

(*-

[SECTION: Section 1: The General Libraries]
[CHAPTER: Chapter 1: The General Functions Libraries]

[TEXT]


<yodle fodle>

The general functions library contains several mish-mash and doo-paa
functions that help with general everyday programing chores such as
taking _out_ the ~garbage~, cleaning your room, and doing the dishes.

The general function library is broken up into several categories:

  <<The smitty foo-bah functions>>

    the smitty foo-bah functions assist with the general ka'ichs pormal
    dorshinglefangle corpus d'ahnk.  ==bold is cool== or is it not?

  <<The dongle-w'achci functions>>

    the smitty foo-bah functions assist with the general ka'ichs pormal
    dorshinglefangle corpus d'ahnk.

  <<The smig-for-kahn functions>>

  [FILE:VTEST.PAS]

  [GRAPHIC:SDFS.EPS]

    the smitty foo-bah functions assist with the general ka'ichs pormal
    dorshinglefangle corpus d'ahnk.

    <<<tingle-kahn-for>>>

      smitty witth ka chi mo bo

      zang forn lack for me to be

      +++++++++++++++++++++++++++++++++++++++++++++++
      +                                             +
      + Note:  The small poo bear will often yell   +
      | yogle at piglet.  This should be ignored    +
      + except when in an interrupt handler.        +
      +                                             +
      +++++++++++++++++++++++++++++++++++++++++++++++


  <<the return until functions>>



-*)

UNIT VGen;



Uses

  DOS,
  VBios,
  VTypes;

{────────────────────────────────────────────────────────────────────────────}

Type

  TPad  =  ( Left, Center, Right );

  {---}

  TSortProc = Function( Var A; Var B ) : SHORTINT;
  PSortProc = ^TSortProc;

{────────────────────────────────────────────────────────────────────────────}

{----------------------}
{ Character and String }
{----------------------}

Function  DeleteChars(            S              : STRING;
                                  Ch             : CHAR         ) : STRING;

Function  UpperChar(              C              : CHAR         ) : CHAR;

Function  UpperString(            S              : STRING       ) : STRING;

Function  ProperString(           S              : STRING       ) : STRING;

Function  Pad(                    S              : STRING;
                                  Len            : BYTE;
                                  TypeOPad       : TPad;
                                  Ch             : CHAR         ) : STRING;

Function  Trim(                   S              : STRING;
                                  Len            : BYTE;
                                  TypeOTrim      : TPad         ) : STRING;

Function  TrimChar(               S              : STRING;
                                  TypeOTrim      : TPad;
                                  Ch             : CHAR         ) : STRING;

Function  LowerChar(              Ch             : CHAR         ) : CHAR;

Function  LowerString(            S              : STRING       ) : STRING;

Function  SR(                     Master,
                                  LookFor,
                                  ReplaceWith   : STRING        ) : STRING;



Function  GetNextParam(           SubS          : STRING;
                                  S             : STRING        ) : STRING;


Function  GetNextParamEx(         SubS          : STRING;
                                  S             : STRING;
                                  Delimiter     : CHAR          ) : STRING;


Function  GetParamName(           SubS          : STRING        ) : STRING;


Function  GetParamData(           SubS          : STRING        ) : STRING;




Function  PosBefore(              SubS           : STRING;
                                  S              : STRING;
                                  Index          : BYTE         ) : BYTE;

Function  PosAfter(               SubS           : STRING;
                                  S              : STRING;
                                  Index          : BYTE         ) : BYTE;

Function  PosEnd(                 Subs           : STRING;
                                  S              : STRING       ) : BYTE;

Function  CopyStr(                S1             : STRING;
                                  Index          : INTEGER;
                                  Count          : INTEGER      ) : STRING;

Function  CopyOverStr(            S1             : STRING;
                                  S2             : STRING;
                                  Index          : INTEGER;
                                  Count          : INTEGER      ) : STRING;


Function  OccurStr(               SubS           : STRING;
                                  S              : STRING       ) : BYTE;


Function  TakeWord(           Var S              : STRING       ) : STRING;

Function  TakeQuote(          Var S              : STRING       ) : STRING;

Function  AddCommas(              S              : STRING       ) : STRING;

Procedure CRC16String(            S              : STRING;
                              Var Result         : WORD;
                                  NewResult      : BOOLEAN      );


Procedure CRC32String(            S              : STRING;
                              Var Result         : LONGINT;
                                  NewResult      : BOOLEAN      );


{---------------------}
{ Validation Routines }
{---------------------}

Function  ValidByte(              S             : STRING        ) : BOOLEAN;

Function  ValidInt(               S             : STRING        ) : BOOLEAN;

Function  ValidLong(              S             : STRING        ) : BOOLEAN;

Function  ValidFloat(             S             : STRING        ) : BOOLEAN;

Function  ValidSci(               S             : STRING        ) : BOOLEAN;

Function  ValidHexByte(           S             : STRING        ) : BOOLEAN;

Function  ValidHexWord(           S             : STRING        ) : BOOLEAN;

Function  ValidHex(               S             : STRING        ) : BOOLEAN;


Function  IsAlpha(                C             : CHAR          ) : BOOLEAN;

Function  IsNum(                  C             : CHAR          ) : BOOLEAN;

Function  IsAlphaNum(             C             : CHAR          ) : BOOLEAN;

Function  IsUpCase(               C             : CHAR          ) : BOOLEAN;

Function  IsLoCase(               C             : CHAR          ) : BOOLEAN;

Function  IsGrammar(              C             : CHAR          ) : BOOLEAN;

Function  IsCtrl(                 C             : CHAR          ) : BOOLEAN;

Function  IsBorder(               C             : CHAR          ) : BOOLEAN;

Function  IsLang(                 C             : CHAR          ) : BOOLEAN;

Function  IsSymbol(               C             : CHAR          ) : BOOLEAN;


{------------------}
{ Type Conversions }
{------------------}

Function  IntToStr(               L             : LONGINT       ) : STRING;

Function  StrToInt(               S             : STRING        ) : LONGINT;

Function  RealToStr(              R             : REAL;
                                  Field         : INTEGER;
                                  Decimals      : INTEGER       ) : STRING;

Function  StrToReal(              S             : STRING        ) : REAL;

Function  SciToStr(               R             : REAL          ) : STRING;

Function  StrToSci(               S             : STRING        ) : REAL;

Function  IntToText(              L             : LONGINT       ) : ST80;

Function  LongToDollars(          L             : LONGINT       ) : REAL;

Function  DollarsToLong(          R             : REAL          ) : LONGINT;


{--------------------------}
{ String Array Conversions }
{--------------------------}

Procedure StrToArray(             S             : STRING;
                              Var TheArray                      );

Function  ArrayToStr(         Var TheArray;
                                  Len           : BYTE          ) : STRING;

Procedure StrToAsciiZ(            S             : STRING;
                              Var AsciiZStr                     );

Function  AsciiZtoStr(        Var AsciiZStr                     ) : STRING;


{---------------}
{ Hex functions }
{---------------}

Function  CharToHex(              C             : SHORTINT      ) : ST80;

Function  ByteToHex(              B             : BYTE          ) : ST80;

Function  IntToHex(               I             : INTEGER       ) : ST80;

Function  WordToHex(              W             : WORD          ) : ST80;

Function  PtrToHex(               P             : POINTER       ) : ST80;

Function  LongToHex(              L             : LONGINT       ) : ST80;

Function  DecToHexStr(            S             : STRING        ) : STRING;

Function  HexToDecStr(            S             : STRING        ) : STRING;

Function  HexToChar(              S             : ST80          ) : SHORTINT;

Function  HexToByte(              S             : ST80          ) : BYTE;

Function  HexToInt(               S             : ST80          ) : INTEGER;

Function  HexToWord(              S             : ST80          ) : WORD;

Function  HexToLong(              S             : ST80          ) : LONGINT;


{------------------}
{ Binary Functions }
{------------------}

Function  ByteToBin(              B             : BYTE          ) : ST80;

Function  IntToBin(               I             : INTEGER       ) : ST80;

Function  WordToBin(              W             : WORD          ) : ST80;

Function  LongToBin(              L             : LONGINT       ) : ST80;


Function  BinToChar(              S             : ST80          ) : SHORTINT;

Function  BinToByte(              S             : ST80          ) : BYTE;

Function  BinToInt(               S             : ST80          ) : INTEGER;

Function  BinToWord(              S             : ST80          ) : WORD;

Function  BinToLong(              S             : ST80          ) : LONGINT;


{-----------------}
{ BCD Conversions }
{-----------------}

Function  DecToBCD(               Decimal       : BYTE          ) : BYTE;

Function  BCDtoDec(               Bcd           : BYTE          ) : BYTE;

Function  ByteToBCD(              Decimal       : BYTE          ) : WORD;

Function  BCDtoByte(              Bcd           : WORD          ) : BYTE;

Function  WordToBCD(              Decimal       : WORD          ) : LONGINT;

Function  BCDtoWord(              Bcd           : LONGINT       ) : WORD;


(* NOT IMPLEMENTED YET...

{---------------------------------------------}
{ Generic numeric string to value conversions }
{---------------------------------------------}

Function  StrToByteEx(            S            : STRING         ) : BYTE;

Function  StrToWordEx(            S            : STRING         ) : WORD;

Function  StrToIntEx(             S            : STRING         ) : INTEGER;

Function  StrToLongEx(            S            : STRING         ) : LONGINT;

*)

{--------------------}
{ Variable Comparing }
{--------------------}

Function  FastCompare(        Var Buf1;
                              Var Buf2;
                                  Count         : WORD          ) : WORD;

Function  Compare(            Var Buf1;
                              Var Buf2;
                                  Count         : WORD          ) : WORD;

Function  CompareSmaller(     Var Buf1;
                              Var Buf2;
                                  Count         : WORD          ) : SHORTINT;

Function  CompareBufByte(     Var Buff;
                                  Count         : WORD;
                                  B             : BYTE          ) : WORD;

Function  CompareBufWord(     Var Buff;
                                  Count         : WORD;
                                  W             : WORD          ) : WORD;

Function  LookupByte(             InByte        : BYTE;
                                  Count         : WORD;
                              Var LTable;
                              Var OutByte       : BYTE          ) : BOOLEAN;

Function  LookupWord(             InWord        : WORD;
                                  Count         : WORD;
                              Var LTable;
                              Var OutWord       : WORD          ) : BOOLEAN;

Procedure SwapBuffers(        Var Buf1;
                              Var Buf2;
                                  Count         : WORD          );

Procedure SwapWords(          Var A,
                                  B             : WORD          );

Procedure SwapInts(           Var A,
                                  B             : INTEGER       );

Procedure SwapBytes(          Var A,
                                  B             : BYTE          );

Function  GreaterInt(             A,
                                  B             : INTEGER       ) : INTEGER;

Function  GreaterWord(            A,
                                  B             : WORD          ) : WORD;

Function  GreaterLong(            A,
                                  B             : LONGINT       ) : LONGINT;

Function  LesserInt(              A,
                                  B             : INTEGER       ) : INTEGER;

Function  LesserWord(             A,
                                  B             : WORD          ) : WORD;

Function  LesserLong(             A,
                                  B             : LONGINT       ) : LONGINT;

Procedure FillWord(           Var Buf;
                                  Count         : WORD;
                                  Value         : WORD          );

Procedure FillLong(           Var Buf;
                                  Count         : WORD;
                                  Value         : LONGINT       );

{----------------}
{ System and CPU }
{----------------}

Procedure RebootMachine(          WarmBoot      : BOOLEAN       );

Procedure SetKeyRate(             Delay         : BYTE;
                                  Rate          : BYTE          );
Procedure SetKeyFast;

Procedure PurgeKbdBuf;

Procedure KeyboardOff;

Procedure KeyboardOn;

{---------------}
{ Miscellaneous }
{---------------}

Procedure CRC16Char(          Var Ch            : CHAR;
                              Var Result        : WORD          );

Procedure CRC16Buffer(        Var Buf;
                                  Count         : WORD;
                              Var Result        : WORD          );

Procedure CRC32Char(          Var Ch            : CHAR;
                              Var Result        : LONGINT       );

Procedure CRC32Buffer(        Var Buf;
                                  Count         : WORD;
                              Var Result        : LONGINT       );

Procedure Sort(               Var Buf;
                                  Index         : WORD;
                                  Count         : WORD;
                                  SortProc      : PSortProc;
                                  Params        : STRING        );

Function  SoundexPack(            S             : STRING        ) : WORD;

Function  SoundexUnPack(          W             : WORD          ) : STRING;

Function  SoundexStr(             S             : STRING        ) : STRING;


Function  PtrToLin(               Ptr           : POINTER       ) : LONGINT;

Function  LinToPtr(               Lin           : LONGINT       ) : POINTER;

Function  PtrAdd(                 OrigPtr       : POINTER;
                                  AddOfs        : LONGINT       ) : POINTER;

Function  PtrSub(                 OrigPtr       : POINTER;
                                  SubOfs        : LONGINT       ) : POINTER;

Function  NewString(              S             : STRING        ) : POINTER;

Function  GetHeapString(          HeapStringPtr : PString       ) : STRING;


Procedure DisposeString(          PrevNewString : PString       );


Procedure FarCall(                Proc          : POINTER       );


{════════════════════════════════════════════════════════════════════════════}



──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  DeleteChars(            S              : STRING;
                                  Ch             : CHAR         ) : STRING;

[PARAMETERS]

S           Source String from which to Remove Characters
Ch          Character to Search for and Delete from String

[RETURNS]

String "S" with all instances of character "Ch" removed.

[DESCRIPTION]

Deletes all instances of the specified character from the
specified string.

[SEE-ALSO]

(none)

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := 'V-I-S-I-O-N-I-X';
  S := DeleteChars( S, '-' );

  { S now equals 'VISIONIX' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  UpperChar(              C              : CHAR         ) : CHAR;

[PARAMETERS]

C           The character to convert to Upper Case

[RETURNS]

The Character converted to Upper Case

[DESCRIPTION]

Converts a Character to Upper Case

[SEE-ALSO]

LowerChar
UpperString
LowerString
ProperString

[EXAMPLE]

VAR
  C : CHAR;

BEGIN

  C := UpperChar( 'a' );

  { C now equals 'A' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  UpperString(               S         : STRING  ) : STRING;

[PARAMETERS]

S           String to convert to Upper Case

[RETURNS]

String "S" in all Upper Case

[DESCRIPTION]

Converts an entire string to upper case.

[SEE-ALSO]

LowerString
ProperString
UpperChar
LowerChar

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := 'This is a Test';
  S := UpperString( S );

  { S = 'THIS IS A TEST' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ProperString(               S         : STRING  ) : STRING;

[PARAMETERS]

S           String to Modify

[RETURNS]

String "S" with the First Characters of each word in Upper Case.
All other characters in string "S" are made lower case.

[DESCRIPTION]

Converts the First Character of each Word in the String to
Upper Case.  Converts all other characters to lower case.

[SEE-ALSO]

UpperString
LowerString
UpperChar
LowerChar

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := 'joHN pAUl JOnEs';
  S := ProperString( S );

  { S = 'John Paul Jones' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  Pad(                       S         : STRING;
                                     Len       : BYTE;
                                     TypeOPad  : TPad;
                                     Ch        : CHAR    ) : STRING;

[PARAMETERS]

S           The string to pad
Len         The desired length of the resulting string
TypeOPad    Type of pad operation you wish to perform

                 Left   Adds the pad character to the left of string
                 Right  Adds the pad character to the right of string
                 Center Adds the pad character equally on either side of
                        string
Ch          Character to pad with

[RETURNS]

The newly padded string based on "S"

[DESCRIPTION]

Pads the string "S" with the character "Ch" so that the string is
"len" characters in length.  Three types of padding are supported:
LEFT pads the left of the string, RIGHT pads the right, and CENTER
pads on both sides.

  ++++++++++++++++++++++++++++++++++++++++++++++++++++
  +                                                  +
  + Note: Pad Left = Right Justified, and visa versa +
  +                                                  +
  ++++++++++++++++++++++++++++++++++++++++++++++++++++

[SEE-ALSO]

Trim

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  {----------------}
  { CENTER padding }
  {----------------}

  S := 'Hello, World';
  S := Pad( S, 20, CENTER, '-' );

  { S now equals '----Hello, World----' }

  {--------------}
  { LEFT padding }
  {--------------}

  S := 'Hello, World';
  S := Pad( S, 20, LEFT, '-' );

  { T now equals '--------Hello, World' }

  {---------------}
  { RIGHT padding }
  {---------------}

  S := 'Hello, World';
  S := Pad( S, 20, RIGHT, '-' );

  { S now equals 'Hello, World--------' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  Trim(                      S         : STRING;
                                     Len       : BYTE;
                                     TypeOTrim : TPad   ) : STRING;

[PARAMETERS]

S           The string to pad
Len         The desired length of the resulting string
TypeOTrim   Type of trim operation you wish to perform
                 Left   Removes characters from the left of the string
                 Right  Removes characters from the right of string
                 Center Removed characters equally on either side of
                        string

[RETURNS]

The newly trimmed string

[DESCRIPTION]

Trims the string "S".  If the "TypeOTrim" is LEFT, characters are
removed from the left side of the string until the length of the
string is "len".  If the "TypeOTrim" is RIGHT, characters are
removed from the right side of the string until the length of the
string is "len".  If the "TypeOTrim" is CENTER, characters are
removed from both sides of the string until the length is "len".

Trim and Pad are inverse functions - one repairs the other.

[SEE-ALSO]

Pad

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  {-----------}
  { Trim LEFT }
  {-----------}

  S := TrimChar( '----Hello, World----', LEFT, 18 )

  { S now equals '--Hello, World----' }

  {------------}
  { Trim RIGHT }
  {------------}

  S := TrimChar( '----Hello, World----', RIGHT, 18 )

  { S now equals '----Hello, World--' }

  {-------------}
  { Trim CENTER }
  {-------------}

  S := TrimChar( '----Hello, World----', CENTER, 18 )

  { S now equals '---Hello, World---' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  TrimChar(                  S         : STRING;
                                     TypeOTrim : TPad;
                                     Ch        : CHAR    ) : STRING;

[PARAMETERS]

S           The string to pad
TypeOTrim   Type of trim operation you wish to perform
                 Left   Removes a character from the left of the string
                 Right  Removes a character from the right of string
                 Center Removed a character equally on either side of
                        string
Ch          Character to trim from side.  This prevents trimming of part
            of the data which happens to also be of the same pad char.

[RETURNS]

The newly trimmed string

[DESCRIPTION]

Trims the string "S".  If the "TypeOTrim" is LEFT, all leading
occurances of the character "CH" are removed from the string.
If the "TypeOTrim" is RIGHT, all trailing occurances of the character
"CH" are removed from the string.  If the "TypeOTrim" is CENTER, all
leading and trailing occurances of the character "CH" are removed
from the string.

[SEE-ALSO]

Pad
Trim

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  {-----------}
  { Trim LEFT }
  {-----------}

  S := TrimChar( '----Hello, World!----', LEFT, '-' )

  { S now equals 'Hello, World!----' }

  {------------}
  { Trim RIGHT }
  {------------}

  S := TrimChar( '----Hello, World!----', RIGHT, '-' )

  { S now equals '----Hello, World!' }

  {-------------}
  { Trim CENTER }
  {-------------}

  S := TrimChar( '----Hello, World!----', CENTER, '-' )

  { S now equals 'Hello, World!' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LowerChar(                 Ch        : CHAR    ) : CHAR;

[PARAMETERS]

Ch          The character to convert to lowercase

[RETURNS]

A lowercase character

[DESCRIPTION]

Converts a the specified character to Lower Case.

[SEE-ALSO]

UpperChar
UpperString
LowerString

[EXAMPLE]

VAR
  C : CHAR;

BEGIN

  C := LowerChar( 'A' );

  { C = 'a' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LowerString(               S         : STRING  ) : STRING;

[PARAMETERS]

S           String to convert the lowercase

[RETURNS]

A lowercase string.

[DESCRIPTION]

Converts the string "S" to lower case.

[SEE-ALSO]

LowerChar
UpperChar
UpperString

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := LowerString( 'Now is the TIME for AlL...' );

  { S now equals 'now is the time for all...' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  SR(                        Master,
                                     LookFor,
                                     ReplaceWith : STRING) : STRING;

[PARAMETERS]

Master      String to perform the search and replace on
LookFor     String to look for in "Master"
ReplaceWith String to replace "LookFor" with.

[RETURNS]

A new string, based on "Master", that has all occurances of the
string "LookFor" replaced with "ReplaceWith".

[DESCRIPTION]

Using a given String, Searches for the sub-string "Lookfor" and replaces
all instances with of it with another sub-string, "ReplaceWith"

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+                                                                 +
+ Note: the SR function can be used to delete all occurances of a +
+ substring within a string by specifying nothing ('') as the     +
+ ReplaceWith parameter.                                          +
+                                                                 +
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

[SEE-ALSO]

(none)

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := SR( 'Now is the time.  Now I Say!', 'Now', 'Tomorrow' );

  { S now equals 'Tomorrow is the time.  Tomorrow I Say!' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  GetNextParam(              SubS      : STRING;
                                     S         : STRING  ) : STRING;

[PARAMETERS]

Subs        Sub-string that preceeds up to the parameter to get
S           Parameter list to get the next parameter from

[RETURNS]

The next Parameter following the given Starting Parameter Sub-String

[DESCRIPTION]

This function takes a string of text parameters (delimited by commas) and
searches for the parameter following the one provided.  The parameter may
be a single symbol or have a value following it (using an equals sign as
in the examples below).
The following Examples illustrate usage:
  Ex #1 : GetNextParam( 'B=C', 'A=B,B=C,C=D,D=10' ) = 'C=D'
  Ex #2 : GetNextParam( '',    'A=B,B=C,C=D,D=10' ) = 'A=B'
  Ex #3 : GetNextParam( 'B',   'A=B,B=C,C=D,D=10' ) = 'C=D'

[SEE-ALSO]

GetNextParamEx
GetParamName
GetParamData

[EXAMPLE]

VAR
  S,T : STRING;

BEGIN

  S := 'Ground=Brown,Sky=Blue,Trees=Green,World=Round';
  T := '';

  REPEAT

    S := GetNextParam( T, S );
    WriteLn( 'T="', T, '"' );

  UNTIL T = '';

  {----------------}
  { Output:        }
  {                }
  { "Ground=Brown" }
  { "Sky=Blue"     }
  { "Trees=Green"  }
  { "World=Round"  }
  {----------------}

  S := 'Ground=Brown,Sky=Blue,Trees=Green,World=Round';
  T := GetNextParam( 'Sky', S );

  { T = 'Trees=Green' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  GetNextParamEx(            SubS      : STRING;
                                     S         : STRING;
                                     Delimiter : CHAR    ) : STRING;

[PARAMETERS]

Subs        Sub-String that preceeds up to the parameter to get
S           Parameter list to get the next parameter from
Delimiter   Sub-String Separator Character

[RETURNS]

The next Parameter following the given Starting Parameter Sub-String.

[DESCRIPTION]

This function takes a string of text parameters (delimited by the
specified "Delimiter") and searches for the parameter following the one
provided.  The parameter may be a single symbol or have a value
following it (using an equals sign as in the examples below).

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+                                                                 +
+ Note:  This function is an EXtended version of the GetNextParam +
+ function, with the extension of being able to specify the       +
+ character that seperates the parameters of a parameter string.  +
+                                                                 +
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

[SEE-ALSO]

GetNextParam
GetParamName
GetParamData

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  {------------}
  { Example #1 }
  {------------}

  S := GetNextParam( '',
                     'Ground=Brown,Sky=Blue|Trees=Green,World=Round',
                     '|' )

  { S now equals 'Ground=Brown,Sky=Blue' }

  {------------}
  { Example #2 }
  {------------}

  S := GetNextParam( 'Ground=Brown,Sky=Blue',
                     'Ground=Brown,Sky=Blue|Trees=Green,World=Round',
                     '|' )

  { S now equals 'Trees=Green,World=Round' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  GetParamName(              SubS      : STRING  ) : STRING;

[PARAMETERS]

SubS        Source Parameter String

[RETURNS]

Parameter Field Name from Source String

[DESCRIPTION]

This function returns the parameter name portion of a parameter string.
The parameter name portion is defined to be "the portion preceding the
equal sign."

[SEE-ALSO]

GetNextParamEx
PosNextData

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := GetParamName( 'Trees=Green' );

  { S now equals 'Trees' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  GetParamData(               SubS      : STRING  ) : STRING;

[PARAMETERS]

SubS        Source Parameter String with Value

[RETURNS]

Parameter Field Value from Source String

[DESCRIPTION]

This function returns the data portion of a parameter string.  The
data portion is defined as "the portion following the equal sign".

[SEE-ALSO]

GetNextParamEx
GetParamName

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := GetParamData( 'Trees=Green' );

  { T now equals 'Green' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  PosBefore(                 SubS      : STRING;
                                     S         : STRING;
                                     Index     : BYTE    ) : BYTE;

[PARAMETERS]

SubS        Sub-String to locate
S           Source String to search
Index       Limiting Search Index

[RETURNS]

Index into Source String where Sub-String was Found

[DESCRIPTION]

This function is much like the standard POS function.  PosBefore
differs in that you can specify the "Index" at which to end the search.
If the specified "SubS"tring occurs before "Index", it's position will
be returned.  If it occurs after the "Index", or if it does not occur
in "S", the function will return a 0.

[SEE-ALSO]

PosNext
PosAfter
PosEnd

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  {------------}
  { Example #1 }
  {------------}

  X := PosBefore( 'World',
                  'Hello, World!  Whats up?',
                  11  );

  (X now equals 0, since the string 'World' does not completely occur
   before the 11th character in the main string)

  {------------}
  { Example #2 }
  {------------}

  X := PosBefore( 'World',
                  'Hello, World!  Whats up?',
                  20  );


  {------------------------------------------------------------}
  { S now equals 8, since the string 'World' occurs before the }
  { 20th character in the main string, at the 8th character    }
  {------------------------------------------------------------}

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  PosAfter(                  SubS      : STRING;
                                     S         : STRING;
                                     Index     : BYTE    ) : BYTE;

[PARAMETERS]

SubS        Sub-String to locate
S           Source String to search
Index       Starting Search Index

[RETURNS]

Index into Source String where Sub-String was Found

[DESCRIPTION]

This function is much like the standard POS function.  PosAfter
differs in that you can specify the "Index" at which to start the search.
If the specified "SubS"tring occurs after "Index", it's position will
be returned.  If it occurs before the "Index", or if it does not occur
in "S", the function will return a 0.

[SEE-ALSO]

Pos
PosNext
PosBefore
PosEnd

[EXAMPLE]

VAR
  B : BYTE;

BEGIN

  B := PosAfter( 'Hello', 'Excuse me, but: Hello, World!  Whats up?', 20 );

  {-----------------------------------------------------------}
  { B now equals 0, since the complete substring "Hello" does }
  { not occur after the 20th character of the main string     }
  {-----------------------------------------------------------}

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function   PosEnd(                   Subs      : STRING;
                                     S         : STRING  ) : BYTE;

[PARAMETERS]

SubS        Sub-String
S           Source String to Search

[RETURNS]

Index into Source String where Sub-String was Found

[DESCRIPTION]

This function is much like the standard POS function.  PosEnd differs
in that the Search is started from the end of the string with the
last Matching Sub-String in the Source String being the Answer.  If
Found this function will return the Index of the Sub-String into the
Source String, otherwise it will return 0 (Just like std POS function).

[SEE-ALSO]

Pos
PosNext
PosBefore
PosAfter

[EXAMPLE]

VAR
  B : BYTE;

BEGIN

  B := PosEnd( 'Hello', 'Excuse me, but: Hello, World!  Whats up?' );

  { B = 17 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  CopyStr(                   S1        : STRING;
                                     Index     : INTEGER;
                                     Count     : INTEGER ) : STRING;

[PARAMETERS]

S1          Source String to Copy with
Index       Position in Source String to Start Copy from
Count       Number of Characters to Copy

[RETURNS]

Created String

[DESCRIPTION]

This function is like the standard Turbo Pascal "Copy" Command, except
it is faster.

[SEE-ALSO]

CopyOverStr

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := Copy( 'The Color is Blue.', 14, 4 );

  { S now equals "Blue" }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  CopyOverStr(               S1        : STRING;
                                     S2        : STRING;
                                     Index     : INTEGER;
                                     Count     : INTEGER  ) : STRING;

[PARAMETERS]

S1          Source String - data to overwrite on S2
S2          Destination String - portion of which overwritten by S1
Index       Position into S2 to Start copying
Count       Number of Characters to Copy

[RETURNS]

Resulting modified string.

[DESCRIPTION]

This function takes the Source String, and uses it to overwrite a portion
of the Destination String, starting from the provided Index and for a
given number of Characters.

[SEE-ALSO]

CopyStr

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := 'The Color is Cyan.';
  S := CopyOverStr( S, 'Blue', 14, 4 );

  { S now equals "The Color is Blue." }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  OccurStr(                  SubS      : STRING;
                                     S         : STRING   ) : BYTE;

[PARAMETERS]

SubS        Sub-String to look for
S           Source String to Search

[RETURNS]

The Number of Times the Sub-String was found in the Source String.

[DESCRIPTION]

Searches the Source String for the Sub-String and returns the number
of times it was found in the Source String.

[SEE-ALSO]

Pos

[EXAMPLE]

VAR
  S     : STRING;
  Count : BYTE;

BEGIN

  S     := 'This is the way it is here.';
  Count := OccurStr( 'is', S );

  { Count = 3 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  TakeWord(              Var S         : STRING   ) : STRING;

[PARAMETERS]

S           VAR Source & Modified String to parse

[RETURNS]

First Text Word found in the provided Source String

[DESCRIPTION]

This function searches the Source String for the first Text Word and
returns that Word as the function result.  The Source String is modified
to remove the found word, which may be resubmitted by the caller to
continue word extractions.

[SEE-ALSO]

TakeQuote

[EXAMPLE]

VAR
  S,Tmp : STRING;

BEGIN

  S := 'This is a string with 9 words in it';

  REPEAT

    Tmp := TakeWord( S );
    WriteLn( Tmp );  { Writes one word at a time }

  UNTIL S = '';

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  TakeQuote(             Var S         : STRING   ) : STRING;

[PARAMETERS]

S           VAR Source & Modified String to parse

[RETURNS]

First Quoted Text found in Source String

[DESCRIPTION]

This function searches the Source String for the first Quoted Text
contained within the provided string and returns this as the function
result.  The Source String is modified by the elimination of the Quoted
Text from within this string.

[SEE-ALSO]

TakeWord

[EXAMPLE]

VAR
  S,T : STRING;

BEGIN

  S := 'The Password is "Zulu"';
  T := TakeQuote( S );

  {------------------------}
  { T = 'Zulu'             }
  { S = 'The Password is ' }
  {------------------------}

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  AddCommas(                 S         : STRING   ) : STRING;

[PARAMETERS]

S           Text String of a Number

[RETURNS]

Number Text with Commas Inserted.

[DESCRIPTION]

This function takes a Number in Text format (like "10", not "ten") and
inserts the commas at the thousands place, etc. until the number has
been completed.

[SEE-ALSO]

(None)

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := '123456789';
  S := AddCommas( S );

  { S = '123,456,789' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure CRC16String(               S         : STRING;
                                 Var Result    : WORD;
                                     NewResult : BOOLEAN  );

[PARAMETERS]

S           Source String to CRC
Result      VAR Returned 16-bit CRC of String
NewResult   Is this an Initial CRC?

[RETURNS]

Function : None
(VAR     : [Result] Returned 16-bit CRC of string)

[DESCRIPTION]

Computes a 16-Bit CRC on the source string.  If the NewResult flag is TRUE
then the Result is based upon the provided string.  If the NewResult Flag is
FALSE then the result is computed as a continuation of the result already
provided in the result variable.

[SEE-ALSO]

CRC16Char
CRC16Buffer
CRC32Char
CRC32String
CRC32Buffer

[EXAMPLE]

VAR
  S      : STRING;
  CRC32  : LONGINT;
  NewCRC : BOOLEAN;
BEGIN

VAR
  S     : STRING;
  CRC16 : WORD;

BEGIN

  S := 'She sells sea shells down by the sea shore';
  CRC16String( S, CRC32, TRUE );

  { CRC16 = $4941 }

END;


──────────────────────────────────────────────────────────────────────────────

[FUNCTION]

Procedure CRC32String(               S         : STRING;
                                 Var Result    : LONGINT;
                                     NewResult : BOOLEAN  );

[PARAMETERS]

S           Source String to CRC
Result      VAR Returned 32-bit CRC Checksum of String
NewResult   Is this an Initial CRC Checksum?

[RETURNS]

Function : None
(VAR     : [Result] Returned 32-bit CRC Checksum of String)

[DESCRIPTION]

Computes a 32-Bit CRC Checksum on the Source String.  If the NewResult
Flag is TRUE then the checksum is based wholey upon the provided string
If the NewResult Flag is FALSE then the Checksum is computed as a
continuation of the Checksum already provided in the Result Variable.

[SEE-ALSO]

CRC16Char
CRC16String
CRC16Buffer
CRC32Char
CRC32Buffer

[EXAMPLE]

VAR
  S     : STRING;
  CRC32 : LONGINT;

BEGIN

  S := 'She sells sea shells down by the sea shore';
  CRC32String( S, CRC32, TRUE );

  { CRC32 = $7C6912A6 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]


Function  ValidByte(                 S         : STRING  ) : BOOLEAN;

[PARAMETERS]

S           String representing a byte value

[RETURNS]

Whether that string did represent a byte value

[DESCRIPTION]

Returns whether or not the given String represents a Valid Byte
Value.

[SEE-ALSO]

ValidInt      ValidLong     ValidFlot    ValidSci
ValidHexByte  ValidHexWord  ValidHex

[EXAMPLE]

BEGIN

  WriteLn( ValidByte( '123' ) );  { TRUE  }
  WriteLn( ValidByte( '345' ) );  { FALSE }
  WriteLn( ValidByte( 'abc' ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ValidInt(                  S         : STRING  ) : BOOLEAN;

[PARAMETERS]

S           String representing a Signed Integer value (Word)

[RETURNS]

Whether that string did represent a signed integer value

[DESCRIPTION]

Returns whether or not the given String represents a Valid
Integer Value.

[SEE-ALSO]

ValidByte
ValidLong
ValidFloat
ValidSci
ValidHexByte
ValidHexWord
ValidHex

[EXAMPLE]

BEGIN

  WriteLn( ValidInt( '12345'  ) );  { TRUE  }
  WriteLn( ValidInt( '123456' ) );  { FALSE }
  WriteLn( ValidInt( 'abcdef' ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ValidLong(                 S         : STRING  ) : BOOLEAN;

[PARAMETERS]
S           String representing a Signed Longint value (Double Word)

[RETURNS]

Whether that string did represent a signed longint value

[DESCRIPTION]

Returns whether or not the given String represents a Valid
Long Integer Value.

[SEE-ALSO]

ValidByte
ValidInt
ValidFloat
ValidSci
ValidHexByte
ValidHexWord
ValidHex

[EXAMPLE]

BEGIN

  WriteLn( ValidLong( '12345678'     ) );  { TRUE }
  WriteLn( ValidLong( '999999999999' ) );  { FALSE }
  WriteLn( ValidLong( 'abcdefgh'     ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ValidFloat(                S         : STRING  ) : BOOLEAN;

[PARAMETERS]

S           String value representing a floating point value

[RETURNS]

Whether that string did represent a floating point value

[DESCRIPTION]

Returns whether or not the given String represents a Valid
Floating Point Value.

[SEE-ALSO]

ValidByte
ValidInt
ValidLong
ValidSci
ValidHexByte
ValidHexWord
ValidHex

[EXAMPLE]

BEGIN

  WriteLn( ValidFloat( '123.456' ) );  { TRUE  }
  WriteLn( ValidFloat( 'abcdefg' ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ValidSci(                  S         : STRING  ) : BOOLEAN;

[PARAMETERS]

S           String representing a floating point value in scientific
            notation

[RETURNS]

Whether that string did represent a floating point value in scientific
notation

[DESCRIPTION]

Returns whether or not the given String represents a Valid
Scientific Notation Floating Point Value.

[SEE-ALSO]

ValidByte
ValidInt
ValidLong
ValidFloat
ValidHexByte
ValidHexWord
ValidHex

[EXAMPLE]

BEGIN

  WriteLn( ValidSci( '1.234E10' ) );  { TRUE  }
  WriteLn( ValidSci( '12.34E10' ) );  { TRUE  }
  WriteLn( ValidSci( '1.234E99' ) );  { FALSE }
  WriteLn( ValidSci( '1.234X10' ) );  { FALSE }
  WriteLn( ValidSci( '12345678' ) );  { TRUE  }
  WriteLn( ValidSci( 'abcdefgh' ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ValidHexByte(              S         : STRING  ) : BOOLEAN;

[PARAMETERS]

S           String representing Byte value in hex

[RETURNS]

Whether that string did represent a byte value in hex

[DESCRIPTION]

Returns whether or not the given String represents a Valid
Byte in Hexadecimal format.

[SEE-ALSO]

ValidByte
ValidInt
ValidLong
ValidFloat
ValidSci
ValidHexWord
ValidHex

[EXAMPLE]

BEGIN

  WriteLn( Valid( '1A'   ) );  { TRUE  }
  WriteLn( Valid( 'Ff'   ) );  { TRUE  }
  WriteLn( Valid( '1A2b' ) );  { FALSE }
  WriteLn( Valid( 'zyx'  ) );  { FALSE }
  WriteLn( Valid( '2'    ) );  { TRUE  }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ValidHexWord(              S         : STRING  ) : BOOLEAN;

[PARAMETERS]

S           String representing a Word value in hex

[RETURNS]

Whether that string did represent a word value in hex

[DESCRIPTION]

Returns whether or not the given String represents a Valid
Word in Hexadecimal format.

[SEE-ALSO]

ValidByte
ValidInt
ValidLong
ValidFloat
ValidSci
ValidHexByte
ValidHex

[EXAMPLE]

BEGIN

  WriteLn( ValidHexWord( '1A2B'  ) );  { TRUE  }
  WriteLn( ValidHexWord( 'FFFf'  ) );  { TRUE  }
  WriteLn( ValidHexWord( '12345' ) );  { FALSE }
  WriteLn( ValidHexWord( 'zyxw'  ) );  { FALSE }
  WriteLn( ValidHexWord( '12'    ) );  { TRUE  }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ValidHex(                  S         : STRING  ) : BOOLEAN;

[PARAMETERS]

S           String representing a Word value in hex

[RETURNS]

Whether that string did represent a word value in hex

[DESCRIPTION]

Returns whether or not the given String represents a Valid
value in Hexadecimal format.  This function doesn't consider
length to be of consideration.  It simply checks that throughout
the entire length of the string, every character is within the
valid range of a Hex character.

[SEE-ALSO]

ValidByte
ValidInt
ValidLong
ValidFloat
ValidSci
ValidHexByte
ValidHex

[EXAMPLE]

BEGIN

  WriteLn( ValidHex( '1D'      ) );  { TRUE  }
  WriteLn( ValidHex( '15DF'    ) );  { TRUE  }
  WriteLn( ValidHex( 'zwyvx'   ) );  { FALSE }
  WriteLn( ValidHex( '153FD85' ) );  { TRUE  }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsAlpha(                   C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

Source character to be tested.

[RETURNS]

Was this character an Alphabetic Character?

[DESCRIPTION]

Test char to ensure that it is an alphabetic char and returns the result.
An alphabetic char is defined as... all alphabetic chars (both upper
and lower case) including foreign language inflections.

[SEE-ALSO]

IsNum
IsAlphaNum
IsUpCase
IsLoCase
IsGrammar
IsCtrl
IsBorder
IsLang
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsAlpha( 'a' ) );  { TRUE  }
  WriteLn( IsAlpha( 'A' ) );  { TRUE  }
  WriteLn( IsAlpha( '8' ) );  { FALSE }
  WriteLn( IsAlpha( '-' ) );  { FALSE }
  WriteLn( IsAlpha( 'ë' ) );  { TRUE  - Note: It includes Foreign Text! }
  WriteLn( IsAlpha( 'Æ' ) );  { TRUE  }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsNum(                     C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Source Character to be tested.

[RETURNS]

Whether that character did represent a numeric char

[DESCRIPTION]

Test char to ensure that it is a numeric char and returns the result.
A numeric char is defined as... all chars from ASCII xx to ASCII xx

[SEE-ALSO]

IsAlpha
IsAlphaNum
IsUpCase
IsLoCase
IsGrammar
IsCtrl
IsBorder
IsLang
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsNum( '4' ) );  { TRUE  }
  WriteLn( IsNum( 'K' ) );  { FALSE }
  WriteLn( IsNum( '#' ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsAlphaNum(                C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Source Character character to be tested

[RETURNS]

Whether that character did represent an alpha-numeric char

[DESCRIPTION]

Tests char to ensure that it is alpha-numeric and returns result.
An alpha-numeric char is defined as... all numeric and alphbetic
chars (both upper and lower case) including foreign language inflections.

[SEE-ALSO]

IsAlpha
IsNum
IsUpCase
IsLoCase
IsGrammar
IsCtrl
IsBorder
IsLang
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsAlphaNum( 'a' ) );  { TRUE  }
  WriteLn( IsAlphaNum( 'A' ) );  { TRUE  }
  WriteLn( IsAlphaNum( ' ' ) );  { FALSE }
  WriteLn( IsAlphaNum( '4' ) );  { TRUE  }
  WriteLn( IsAlphaNum( '&' ) );  { FALSE }
  WriteLn( IsAlphaNum( 'ü' ) );  { TRUE  }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsUpCase(                  C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Source Character to be tested

[RETURNS]

Whether that character did represent an upper case char of any language

[DESCRIPTION]

Tests char to ensure that it is an upper case char (whether English or
Foreign Inflection) and returns result.

[SEE-ALSO]

IsAlpha
IsNum
IsAlphaNum
IsLoCase
IsGrammar
IsCtrl
IsBorder
IsLang
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsUpCase( 'A' ) );  { TRUE  }
  WriteLn( IsUpCase( 'a' ) );  { FALSE }
  WriteLn( IsUpCase( 'ü' ) );  { FALSE }
  WriteLn( IsUpCase( 'Æ' ) );  { TRUE  }
  WriteLn( IsUpCase( '%' ) );  { FALSE }
  WriteLn( IsUpCase( '3' ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsLoCase(                  C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Source Character to be tested

[RETURNS]

Whether that character did represent a lower case char in any language.

[DESCRIPTION]

Tests char to ensure that it is a lower case char (whether English or
Foreign Imflection) and returns result.

[SEE-ALSO]

IsAlpha
IsNum
IsAlphaNum
IsUpCase
IsGrammar
IsCtrl
IsBorder
IsLang
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsUpCase( 'A' ) );  { FALSE }
  WriteLn( IsUpCase( 'a' ) );  { TRUE  }
  WriteLn( IsUpCase( 'ü' ) );  { TRUE  }
  WriteLn( IsUpCase( 'Æ' ) );  { FALSE }
  WriteLn( IsUpCase( '%' ) );  { FALSE }
  WriteLn( IsUpCase( '3' ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsGrammar(                 C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Source Character to be tested

[RETURNS]

Whether that character did represent a grammar char

[DESCRIPTION]

Tests char to ensure that it is a grammar char and returns result.
This includes all standard grammar symbols as well as all math and
currency symbols.

[SEE-ALSO]

IsAlpha
IsNum
IsAlphaNum
IsUpCase
IsLoCase
IsCtrl
IsBorder
IsLang
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsGrammar( '.' ) );  { TRUE  }
  WriteLn( IsGrammar( '!' ) );  { TRUE  }
  WriteLn( IsGrammar( 'd' ) );  { FALSE }
  WriteLn( IsGrammar( '6' ) );  { FALSE }
  WriteLn( IsGrammar( '&' ) );  { TRUE  }
  WriteLn( IsGrammar( '/' ) );  { TRUE  }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsCtrl(                    C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Source Character to be tested.

[RETURNS]

Whether that character did represent a control character

[DESCRIPTION]

Tests char to ensure that it is a control char and returns the result.
A control char is defined as all chars below the ASCII value of 32.

[SEE-ALSO]

IsAlpha
IsNum
IsAlphaNum
IsUpCase
IsLoCase
IsGrammar
IsBorder
IsLang
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsCtrl( #13 ) );  { TRUE  }
  WriteLn( IsCtrl( #26 ) );  { TRUE  }
  WriteLn( IsCtrl( #32 ) );  { FALSE }
  WriteLn( IsCtrl( #97 ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsBorder(                  C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Source Character to be tested.

[RETURNS]

Whether that character did represent a border character.

[DESCRIPTION]

Tests char to ensure that it is a border char and returns the result.
A border char is defined as all line drawing chars as well as
non-graphic text chars (vertical bar,plus, and dash) in addition
to solid boxes.

Except where the ASCII value is below 128, these chars are represented
as those that extend and touch the adjacent chars.

[SEE-ALSO]

IsAlpha
IsNum
IsAlphaNum
IsUpCase
IsLoCase
IsGrammar
IsCtrl
IsLang
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsBorder( '╔' ) );  { TRUE  }
  WriteLn( IsBorder( '┼' ) );  { TRUE  }
  WriteLn( IsBorder( 'a' ) );  { FALSE }
  WriteLn( IsBorder( '7' ) );  { FALSE }
  WriteLn( IsBorder( '█' ) );  { TRUE  }
  WriteLn( IsBorder( '&' ) );  { FALSE }
  WriteLn( IsBorder( '-' ) );  { TRUE  - Text Mode Borders }
  WriteLn( IsBorder( '|' ) );  { TRUE  }
  WriteLn( IsBorder( '+' ) );  { TRUE  }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsLang(                    C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Source Character to be tested.

[RETURNS]

Whether that character did represent a Foreign Language character.

[DESCRIPTION]

Test char to ensure that it is a language char and returns the result.
A language char is defined as all Foreign Language Alphbetic chars
(essentially those alpha chars containing foreign language inflections)

[SEE-ALSO]

IsAlpha
IsNum
IsAlphaNum
IsUpCase
IsLoCase
IsGrammar
IsCtrl
IsBorder
IsSymbol

[EXAMPLE]

BEGIN

  WriteLn( IsLang( 'Ä' ) );  { TRUE  }
  WriteLn( IsLang( 'ü' ) );  { TRUE  }
  WriteLn( IsLang( 'a' ) );  { FALSE }
  WriteLn( IsLang( 'Q' ) );  { FALSE }
  WriteLn( IsLang( '6' ) );  { FALSE }
  WriteLn( IsLang( '&' ) );  { FALSE }
  WriteLn( IsLang( '╔' ) );  { FALSE }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IsSymbol(                  C         : CHAR    ) : BOOLEAN;

[PARAMETERS]

C           Character representing a symbol char

[RETURNS]

Whether that character did represent a symbol char

[DESCRIPTION]

Tests char to ensure that it is a symbol char and returns the result.
A border char is defined as all chars excluding the following:
Numeric, Alphabetic (both upper and lower case), all grammar chars,
all border chars, all control characters, and all foreign language
chars.  Basically all misc chars not used by any of the previous tests
and definitions.

[SEE-ALSO]

IsAlpha
IsNum
IsAlphaNum
IsUpCase
IsLoCase
IsGrammar
IsCtrl
IsBorder
IsLang

[EXAMPLE]

BEGIN

  WriteLn( IsSymbol( '≤' ) );  { TRUE  }
  WriteLn( IsSymbol( 'A' ) );  { FALSE }
  WriteLn( IsSymbol( '6' ) );  { FALSE }
  WriteLn( IsSymbol( '#' ) );  { FALSE }
  WriteLn( IsSymbol( '√' ) );  { TRUE  }
  WriteLn( IsSymbol( '╔' ) );  { FALSE }
  WriteLn( IsSymbol( '≈' ) );  { TRUE  }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IntToStr(                  L         : LONGINT ) : STRING;

[PARAMETERS]

L           Longint value to convert to string

[RETURNS]

String representation of integer value

[DESCRIPTION]

Converts an integer value into a string

[SEE-ALSO]

StrToInt

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := IntToStr( 12345 );

  { S = '12345' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  StrToInt(                  S         : STRING  ) : LONGINT;

[PARAMETERS]

S           String to convert to integer value

[RETURNS]

Integer representation of string.  If Error then result is Zero.

[DESCRIPTION]

Converts a string into an integer value.

[SEE-ALSO]

IntToStr

[EXAMPLE]

VAR
  L : LONGINT;

BEGIN

  L := StrToInt( '4312' );

  { L = 4312 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  RealToStr(                 R         : REAL;
                                     Field     : INTEGER;
                                     Decimals  : INTEGER  ) : STRING;

[PARAMETERS]

R           Floating point value to convert to string
Field       Desired final width of string
Decimals    Desired number of decimal places to use in string

[RETURNS]

String representation of Floating point value

[DESCRIPTION]

Converts a floating point value into a string using the given string
width and decimal places.

[SEE-ALSO]

StrToReal

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := RealToStr( 1.5, 8, 4 );

  { S = '  1.5000' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  StrToReal(                 S         : STRING  ) : REAL;

[PARAMETERS]

S           String to convert to a floating point value

[RETURNS]

Floating point representation of string.

[DESCRIPTION]

Converts a string into a floating point value.
If Error then result is Zero.

NOTE: This Function does NOT take care of Leading or Trailing
Spaces or other Symbols.  This MUST be taken care of by the
caller.  All data must be prepared for immediate use.

[SEE-ALSO]

RealToStr

[EXAMPLE]

VAR
  R : REAL;

BEGIN

  R := StrToReal( '1.5' );

  { R = 1.5 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  SciToStr(                  R         : REAL    ) : STRING;

[PARAMETERS]

S           Floating point value to convert to string in scientific notation

[RETURNS]

String representation of floating point value using scientific notation

[DESCRIPTION]

Converts a floating point value into a string using scientific notation.

[SEE-ALSO]

StrToSci

[EXAMPLE]

VAR
  R : REAL;
  S : STRING;

BEGIN

  R := 1.25E2;  { 125 }
  S := SciToStr( R );

  { S = '1.25E2' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  StrToSci(                  S         : STRING  ) : REAL;

[PARAMETERS]

S           String in scientific notation to convert to floating point value

[RETURNS]

Floating point representation of string.  If Error then result is Zero.

[DESCRIPTION]

Converts string of scientific notatation value to a floating point value.
If Error then floating point is Zero.

[SEE-ALSO]

SciToStr

[EXAMPLE]

VAR
  R : REAL;

BEGIN

  R := StrToSci( '1.25E2' );

  { R = 1.25E2 or 125 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IntToText(                 L         : LONGINT ) : ST80;

[PARAMETERS]

L           Integer value to convert to text string

[RETURNS]

Text String representation of integer value.

[DESCRIPTION]

Converts integer value into text form.  Handles all values into the
Billions.  The limiting factor is that the returned string is only
80 chars long and thus will clip any further text.

[SEE-ALSO]


[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := IntToText( 10 );
  { S now equals "Ten" }

  S := IntToText( 1,234,000 );

  { S equals "One Million, Two Hundred Thirty Four Thousand" }


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LongToDollars(             L         : LONGINT ) : REAL;

[PARAMETERS]

L           Currency Value in Cents

[RETURNS]

Currency Value in Dollars.  (Pennies now represented as fractions)

[DESCRIPTION]

Converts an integer penny amount into a floating point dollar amount

[SEE-ALSO]

DollarsToLong

[EXAMPLE]

VAR
  R : REAL;

BEGIN

  R := LongToDollars( 12500 );

  { R = 125.00 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  DollarsToLong(             R         : REAL    ) : LONGINT;

[PARAMETERS]

R           Currency Value in Dollars

[RETURNS]

Currency Value in Cents.  (Dollars now represented as 100 Pennies)

[DESCRIPTION]

Converts a floating point dollar amount into an integer penny amount

[SEE-ALSO]

LongToDollars

[EXAMPLE]

VAR
  L : LONGINT;

BEGIN

  L := DollarsToLong( 125.00 );

  { L = 12500 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure StrToArray(                S         : STRING;
                                 Var TheArray            );

[PARAMETERS]

S           Pascal String to convert to an array
TheArray    VAR working array to return results in

[RETURNS]

Function : None
(Var     : [TheArray] The array of characters so stored)

[DESCRIPTION]

This function converts a PASCAL String into an Array of Characters.
(NOTE: The Array is NOT Zero Terminated or length denoted by any means!)

[SEE-ALSO]

ArrayToStr

[EXAMPLE]

TYPE
  TArr = ARRAY[1..10] of CHAR;

VAR
  S   : STRING;
  Arr : TArr;

BEGIN

  S := 'Hello';
  StrToArray( S, Arr );

  { Arr[1]='H', .. ,Arr[5]='o' }
  { Data Now in Array Format   }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ArrayToStr(            Var TheArray;
                                     Len       : BYTE    ) : STRING;

[PARAMETERS]

TheArray    VAR Address of the source array to convert to a string
Len         Desired final string length

[RETURNS]

Pascal String created from array

[DESCRIPTION]

This function converts an Array of Characters into a PASCAL String.
(NOTE: The input Array need not be terminated in any way, but will
be exactly duplicated up to the length "Len" - even if beyond the
Array!)

[SEE-ALSO]

StrToArray

[EXAMPLE]

TYPE
  TArr = ARRAY[1..10] of CHAR;

VAR
  S   : STRING;
  Arr : TArr;

BEGIN

  Arr[1] := 'Y';
  Arr[2] := 'e';
  Arr[3] := 's';

  S := ArrayToStr( Arr, 3 );

  { S = 'Yes' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure StrToAsciiZ(               S         : STRING;
                                 Var AsciiZStr           );

[PARAMETERS]

S           Pascal String to convert into an AsciiZ String
AsciiZStr   VAR working array ton return AsciiZ string in

[RETURNS]

Function : None
(Var     : [AsciiZStr] The new ASCIIZ String)

[DESCRIPTION]

This Procedure converts a PASCAL String into an ASCIIZ String (a null-
terminated character array).  This is particularly useful when
converting Pascal Strings to C Strings.

[SEE-ALSO]

AsciiZtoStr

[EXAMPLE]

TYPE
  TArr = ARRAY[1..10] of CHAR;

VAR
  S   : STRING;
  Arr : TArr;

BEGIN

  S := 'Yes';
  StrToAsciiZ( S, Arr );

  { Arr[1]='Y' }
  { Arr[2]='e' }
  { Arr[3]='s' }
  { Arr[4]=#0  - NULL Terminated! }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  AsciiZtoStr(           Var AsciiZStr           ) : STRING;

[PARAMETERS]

AsciiZStr   VAR address of source AsciiZ string to convert to a string

[RETURNS]

Pascal String created from AsciiZ source string

[DESCRIPTION]

This function converts an ASCIIZ String (a null-terminated character
array) into a PASCAL String.  This is particularly useful when
converting a C String to a Pascal String.

[SEE-ALSO]

StrToAsciiZ

[EXAMPLE]

TYPE
  TArr = ARRAY[1..10] of CHAR;

VAR
  S   : STRING;
  Arr : TArr;

BEGIN

  Arr[1] := 'Y';
  Arr[2] := 'e';
  Arr[3] := 's';
  Arr[4] := #0;

  S := AsciiZtoStr( Arr );

  { S = 'Yes' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  CharToHex(                 C         : SHORTINT) : ST80;

[PARAMETERS]

C           Signed Byte (SHORTINT) value to convert to a hex string

[RETURNS]

Hex string representation of signed byte value

[DESCRIPTION]

Converts a Signed Byte (Shortint) value into a hexadecimal string

[SEE-ALSO]

ByteToHex
IntToHex
WordToHex
PtrToHex
LongToHex
HexToChar
HexToByte
HexToInt
HexToWord
HexToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := CharToHex( #32 );

  { S = '20' (Hex of 32) }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ByteToHex(                 B         : BYTE    ) : ST80;

[PARAMETERS]

B           Unsigned Byte value to convert to a hex string

[RETURNS]

Hex string representation of byte value

[DESCRIPTION]

Converts an Unsigned Byte Value into a Hexadecimal String

[SEE-ALSO]

CharToHex
IntToHex
WordToHex
PtrToHex
LongToHex
HexToChar
HexToByte
HexToInt
HexToWord
HexToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := ByteToHex( #32 );

  { S = '20' (Hex of 32) }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IntToHex(                  I         : INTEGER ) : ST80;

[PARAMETERS]

I           Signed Word (INTEGER) value to convert to a hex string

[RETURNS]

Hex string representation of signed word value

[DESCRIPTION]

Converts a Signed Word (INTEGER) value into a hexadecimal string

[SEE-ALSO]

CharToHex
ByteToHex
WordToHex
PtrToHex
LongToHex
HexToChar
HexToByte
HexToInt
HexToWord
HexToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := IntToHex( -32000 );

  { S = '8300' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  WordToHex(                 W         : WORD    ) : ST80;

[PARAMETERS]

W           Unsigned Word to convert to a hex string

[RETURNS]

Hex string representation of word value

[DESCRIPTION]

Converts an Unsigned Word into a hexadecimal string

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
PtrToHex
LongToHex
HexToChar
HexToByte
HexToInt
HexToWord
HexToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := WordToHex( 50000 );

  { S = 'C350' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  PtrToHex(                  P         : POINTER ) : ST80;

[PARAMETERS]

P           Pointer to convert to a hex string

[RETURNS]

Hex string representation of pointer value

[DESCRIPTION]

Converts a Pointer into a hexadecimal string (both segment and offset)

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
LongToHex
HexToChar
HexToByte
HexToInt
HexToWord
HexToLong

[EXAMPLE]

VAR
  P : POINTER;
  S : STRING;

BEGIN

  P := Ptr($A000,0);
  S := PtrToHex( P );

  { S = 'A000:0000' }

END;

──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LongToHex(                 L         : LONGINT ) : ST80;

[PARAMETERS]

L           Signed Double Word (LONGINT) Value to convert to a hex string

[RETURNS]

Hex string representation of Longint value

[DESCRIPTION]

Converts a Signed Double Word (LONGINT) into a hexadecimal string

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
PtrToHex
HexToChar
HexToByte
HexToInt
HexToWord
HexToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := LongToHex( 123456789 );

  { S = '075BCD15' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function DecToHexStr(                S         : STRING   ) : STRING;

[PARAMETERS]

S           Decimal Value in String Format

[RETURNS]

Hexidecimal Value String

[DESCRIPTION]

Converts a Decimal Value String into a Hexidecimal Value String.
The Result is 8 Characters Long.  The Caller must strip the any
Leading Zeros to the desired size.

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
PtrToHex
HexToChar
HexToByte
HexToInt
HexToWord
HexToLong
HexToDecStr

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := '1234';
  S := DecToHexStr( S );

  { S = '000004D2' - Caller Must Strip Leading Zeros if desired }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function HexToDecStr(                S         : STRING   ) : STRING;

[PARAMETERS]

S           Hexadecimal Value in String Format

[RETURNS]

Decimal Value String

[DESCRIPTION]

Converts a Hexadecimal Value String into a Decimal Longint Value String.

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
PtrToHex
HexToChar
HexToByte
HexToInt
HexToWord
HexToLong
DecToHexStr

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := '04D2';
  S := HexToDecStr( S );

  { S = '1234', Caller must Strip to Size Desired }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  HexToChar(                 S         : ST80    ) : SHORTINT;

[PARAMETERS]

S           String representation of signed byte hex value

[RETURNS]

Signed byte value represented by hex string

[DESCRIPTION]

Converts a hexadecimal string representation of a signed byte into
a signed byte value.  If Error then value is Zero.

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
PtrToHex
LongToHex
HexToByte
HexToInt
HexToWord
HexToLong

[EXAMPLE]

VAR
  I : SHORTINT;

BEGIN

  I := HexToChar( '80' );

  { I = -128 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  HexToByte(                 S         : ST80    ) : BYTE;

[PARAMETERS]

S           String representation of byte hex value

[RETURNS]

Byte represented by hex string.

[DESCRIPTION]

Converts a hexadecimal string representation of a byte into a byte value.
If Error then value is Zero.

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
PtrToHex
LongToHex
HexToChar
HexToInt
HexToWord
HexToLong

[EXAMPLE]

VAR
  B : BYTE;

BEGIN

  B := HexToByte( '80' );

  { B = 128 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  HexToInt(                  S         : ST80    ) : INTEGER;

[PARAMETERS]

S           String representation of integer hex value

[RETURNS]

Integer represented by hex string

[DESCRIPTION]

Converts a hexadecimal string representation of an integer (signed word)
into an integer value.  If Error then value is Zero.

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
PtrToHex
LongToHex
HexToChar
HexToByte
HexToWord
HexToLong

[EXAMPLE]

VAR
  I : INTEGER;

BEGIN

  I := HexToInt( '8300' );

  { I = -32000 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  HexToWord(                 S         : ST80    ) : WORD;

[PARAMETERS]

S           String representation of a word hex value

[RETURNS]

Word represented by hex string

[DESCRIPTION]

Converts a hexadecimal string representation of a word into a word value.
If Error then value is Zero.

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
PtrToHex
LongToHex
HexToChar
HexToByte
HexToInt
HexToLong

[EXAMPLE]

VAR
  W : WORD;

BEGIN

  W := HexToWord( 'C350' );

  { W = 50000 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  HexToLong(                 S         : ST80    ) : LONGINT;

[PARAMETERS]

S           String representation of longint hex value (double word)

[RETURNS]

Longint represented by hex string

[DESCRIPTION]

Converts a hexadecimal string representation of a longint (signed double
word) into a longint value.  If Error then value is Zero.

[SEE-ALSO]

CharToHex
ByteToHex
IntToHex
WordToHex
PtrToHex
LongToHex
HexToChar
HexToByte
HexToInt
HexToWord

[EXAMPLE]

VAR
  L : LONGINT;

BEGIN

  L := HexToLong( '075BCD15' );

  { L = 123456789 }

END;



──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ByteToBin(                 B         : BYTE    ) : ST80;

[PARAMETERS]

B           Byte value to convert to a binary string

[RETURNS]

Binary string representation of byte value

[DESCRIPTION]

Converts a byte value into a binary string

[SEE-ALSO]

IntToBin
WordToBin
LongToBin
BinToChar
BinToByte
BinToInt
BinToWord
BinToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := ByteToBin( 125 );

  { S = '01111101' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  IntToBin(                  I         : INTEGER ) : ST80;

[PARAMETERS]

I           Integer (signed word) value to convert to a binary string

[RETURNS]

Binary string representation of integer value.

[DESCRIPTION]

Converts a integer (signed word) value into a binary string

[SEE-ALSO]

ByteToBin
WordToBin
LongToBin
BinToChar
BinToByte
BinToInt
BinToWord
BinToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := IntToBin( -32000 );

  { S = '1000001100000000' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  WordToBin(                 W         : WORD    ) : ST80;

[PARAMETERS]

W           Word value to convert to a binary string

[RETURNS]

Binary string representation of word value

[DESCRIPTION]

Converts a word value into a binary string

[SEE-ALSO]

ByteToBin
IntToBin
LongToBin
BinToChar
BinToByte
BinToInt
BinToWord
BinToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := WordToBin( 50000 );

  { S = '1100001101010000' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LongToBin(                 L         : LONGINT ) : ST80;

[PARAMETERS]

L           Longint (signed double word) value to convert to binary string

[RETURNS]

Binary string representation of Longint

[DESCRIPTION]

Converts a longint (signed double word) value into a binary string

[SEE-ALSO]

ByteToBin
IntToBin
WordToBin
BinToChar
BinToByte
BinToInt
BinToWord
BinToLong

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := LongToBin( 123456789 );

  { S = '00000111010110111100110100010101' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  BinToChar(                 S         : ST80    ) : SHORTINT;

[PARAMETERS]

S           Binary string to convert to a signed byte value

[RETURNS]

Signed byte value of binary string

[DESCRIPTION]

Converts a binary string into a signed byte value.
If Error then value is Zero.

[SEE-ALSO]

ByteToBin
IntToBin
WordToBin
LongToBin
BinToByte
BinToInt
BinToWord
BinToLong

[EXAMPLE]

VAR
  I : SHORTINT;

BEGIN

  I := BinToChar( '10000000' );
  { I = -128 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  BinToByte(                 S         : ST80    ) : BYTE;

[PARAMETERS]

S           Binary string to convert to a byte value

[RETURNS]

Byte value of binary string

[DESCRIPTION]

Converts a binary string into an unsigned byte value.
If Error then value is Zero.

[SEE-ALSO]

ByteToBin
IntToBin
WordToBin
LongToBin
BinToChar
BinToInt
BinToWord
BinToLong

[EXAMPLE]

VAR
  B : BYTE;

BEGIN

  B := BinToChar( '10000000' );
  { B = 128 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  BinToInt(                  S         : ST80    ) : INTEGER;

[PARAMETERS]

S           Binary string to convert to an integer (signed word) value

[RETURNS]

Integer value of binary string

[DESCRIPTION]

Converts a binary string into an integer value.
If Error then value is Zero.

[SEE-ALSO]

ByteToBin
IntToBin
WordToBin
LongToBin
BinToChar
BinToByte
BinToWord
BinToLong

[EXAMPLE]

VAR
  I : INTEGER;

BEGIN

  I := BinToInt( '1000001100000000' );

  { I := -32000 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  BinToWord(                 S         : ST80    ) : WORD;

[PARAMETERS]

S           Binary string to convert to a word value

[RETURNS]

Word value of binary string

[DESCRIPTION]

Converts a binary string into a word value.
If Error then value is Zero.

[SEE-ALSO]

ByteToBin
IntToBin
WordToBin
LongToBin
BinToChar
BinToByte
BinToInt
BinToLong

[EXAMPLE]

VAR
  W : WORD;

BEGIN

  W := BinToWord( '1100001101010000' );

  { W = 50000 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  BinToLong(                 S         : ST80    ) : LONGINT;

[PARAMETERS]

S           Binary String to convert to a longint (signed double word) value

[RETURNS]

Longint value of binary string

[DESCRIPTION]

Converts a binary string into a longint value.
If Error then value is Zero.

[SEE-ALSO]

ByteToBin
IntToBin
WordToBin
LongToBin
BinToChar
BinToByte
BinToInt
BinToWord

[EXAMPLE]

VAR
  L : LONGINT;

BEGIN

  L := BinToLong( '00000111010110111100110100010101' );

  { L = 123456789 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  DecToBCD(                  Decimal   : BYTE    ) : BYTE;

[PARAMETERS]

Decimal     Decimal Byte value (ranging from 0 to 99) to convert to a
            BCD byte value.

[RETURNS]

BCD value of Decimal byte value.

[DESCRIPTION]

Converts a decimal value ranging from 0 to 99 to Binary Coded Decimal
Format as a byte.

[SEE-ALSO]

BCDtoDec
ByteToBCD
BCDtoByte
WordToBCD
BCDtoWord

[EXAMPLE]

VAR
  B : BYTE;

BEGIN

  B := DecToBCD( 14 );

  { B = $14 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  BCDtoDec(                  Bcd       : BYTE    ) : BYTE;

[PARAMETERS]

Bcd         BCD Byte value (ranging 00h - 99h) to convert to a decimal
            byte value.

[RETURNS]

Decimal byte value of BCD byte value.

[DESCRIPTION]

Converts a BCD byte value ranging fron 00h to 99h to a decimal byte value

[SEE-ALSO]

DecToBCD
ByteToBCD
BCDtoByte
WordToBCD
BCDtoWord

[EXAMPLE]

VAR
  B : BYTE;

BEGIN

  B := BCDtoDec( $14 );

  { B = 14 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  ByteToBCD(                 Decimal   : BYTE    ) : WORD;

[PARAMETERS]

Decimal     Decimal byte value (ranging from 0 to 255) to convert to
            a BCD word value

[RETURNS]

BCD word value of decimal byte value.

[DESCRIPTION]

Converts a Decimal byte value ranging from 0 to 255 to Binary Coded
Decimal format as a word.

[SEE-ALSO]

DecToBCD
BCDtoDec
BCDtoByte
WordToBCD
BCDtoWord

[EXAMPLE]

VAR
  W : WORD;

BEGIN

  W := ByteToBCD( 255 );

  { W = $0255 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  BCDtoByte(                 Bcd       : WORD    ) : BYTE;

[PARAMETERS]

Bcd         BCD Word value (ranging from 0000h to 0255h) to convert to
            a decimal byte value.

[RETURNS]

Decimal byte value of BCD word value.

[DESCRIPTION]

Converts a BCD word value ranging from 0000h to 0255h to a decimal byte
value.

[SEE-ALSO]

DecToBCD
BCDtoDec
ByteToBCD
WordToBCD
BCDtoWord

[EXAMPLE]

VAR
  B : BYTE;

BEGIN

  B := BCDtoByte( $0255 );

  { B = 255 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  WordToBCD(                 Decimal   : WORD    ) : LONGINT;

[PARAMETERS]

Decimal     Decimal word value (ranging from 0 to 65535) to convert to
            a BCD longint value

[RETURNS]

BCD longint value of decimal word value

[DESCRIPTION]

Converts a Decimal word value ranging from 0 to 65535 to Binary Coded
Decimal format as a longint.

[SEE-ALSO]

DecToBCD
BCDtoDec
ByteToBCD
BCDtoByte
BCDtoWord

[EXAMPLE]

VAR
  L : LONGINT;

BEGIN

  L := WordToBCD( 54321 );

  { L = $00054321 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  BCDtoWord(                 Bcd       : LONGINT ) : WORD;

[PARAMETERS]

Bcd         BCD longint value (ranging from 00000000h to 00065535h) to
            convert to a decimal word value

[RETURNS]

Decimal word value of BCD longint value

[DESCRIPTION]

Converts a BCD longint value ranging fron 00000000h to 00065536h to a
decimal word value.

[SEE-ALSO]

DecToBCD
BCDtoDec
ByteToBCD
BCDtoByte
WordToBCD

[EXAMPLE]

VAR
  W : WORD;

BEGIN

  W := BCDtoWord( $00054321 );

  { W = 54321 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

[PARAMETERS]

[RETURNS]

[DESCRIPTION]

[SEE-ALSO]

[EXAMPLE]


GetStrNumType( '$1234' ) = 2


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

[PARAMETERS]

[RETURNS]

[DESCRIPTION]

[SEE-ALSO]

[EXAMPLE]


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  StrToIntEx(                S         : STRING  ) : INTEGER;

[PARAMETERS]

S           Source String representing Integer Value

[RETURNS]

Integer Value

[DESCRIPTION]

****** THIS FUNCTION NOT IMPLEMENTED! ******

[SEE-ALSO]

[EXAMPLE]


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

[PARAMETERS]

[RETURNS]

[DESCRIPTION]

[SEE-ALSO]

[EXAMPLE]


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  FastCompare(           Var Buf1;
                                 Var Buf2;
                                     Count     : WORD    ) : WORD;

[PARAMETERS]

Buffer1     VAR Address of First Buffer (Generic Type)
Buffer2     VAR Address of Second Buffer (Generic Type)
Count       Number of bytes in each buffer

[RETURNS]

Whether or not the provided Buffers were the same (0=Same, $FFFF=Not)

[DESCRIPTION]

This function compares two data buffers and returns a non-zero value
if the buffers data does not compare.  It doesn't indicate which byte
index the miscompare exists, just that it did.  If the data in both
buffers are alike the result is Zero.  This Operation is Optimized in
Assembly for the fastest possible Comparison.

[SEE-ALSO]

Compare
CompareSmaller
CompareBufByte

[EXAMPLE]

TYPE
  TBuff = ARRAY[1..10] of BYTE;

VAR
  B1,B2 : TBuff;
  W     : WORD;

BEGIN

  FillChar( B1, SizeOf( B1 ), 4 );
  FillChar( B2, SizeOf( B2 ), 4 );

  B2[7] := 49;  { Force MisCompare }

  W := FastCompare( B1, B2, SizeOf( TBuff ) );

  { W = $FFFF  - MisCompared! }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  Compare(               Var Buf1;
                                 Var Buf2;
                                     Count     : WORD    ) : WORD;

[PARAMETERS]

Buf1        VAR Address of First Buffer (Generic Type)
Buf2        VAR Address of Second Buffer (Generic Type)
Count       Number of bytes in each buffer (Max = $FFFE bytes)

[RETURNS]

Index of First Miscompared Byte in Buffers, 0 if Buffers the Same

[DESCRIPTION]

This function compares two data buffers and returns a non-zero value
if the buffer's data does not compare.  This number will be the index
of the first byte miscompared between the two bufffers or Zero if the
buffers were alike.  This Operation is Optimized in Assembly for the
fastests possible Comparison.

[SEE-ALSO]

FastCompare
CompareSmaller
CompareBufByte

[EXAMPLE]

TYPE
  TBuff = ARRAY[1..10] of BYTE;

VAR
  B1,B2 : TBuff;
  W     : WORD;

BEGIN

  FillChar( B1, SizeOf( B1 ), 4 );
  FillChar( B2, SizeOf( B2 ), 4 );

  B2[7] := 49;  { Force MisCompare }

  W := Compare( B1, B2, SizeOf( TBuff ) );

  { W = 7  - MisCompare Index! }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  CompareSmaller(        Var Buf1;
                                 Var Buf2;
                                     Count     : WORD    ) : SHORTINT;

[PARAMETERS]

Buf1        VAR Address of First Buffer (Generic Type)
Buf2        VAR Address of Second Buffer (Generic Type)
Count       Number of bytes in each buffer (Max = $FFFE bytes)

[RETURNS]

Which Buffer Data contains the Smaller Value or if they Match
  -1 if first is smaller than the second buffer
   0 if they are the same
   1 if first is bigger than the second buffer

[DESCRIPTION]

This function tests two buffers to see which Buffer Data contains a smaller
value.  At the first Miscompare, the one with the lesser Value is indicated
with a non-zero value (-1 if the 1st Buffer byte is smaller than the 2nd,
1 if the 1st Buffer byte is greater than the 2nd, or 0 [Zero] if they are
both the same).

[SEE-ALSO]

FastCompare
Compare
CompareBufByte

[EXAMPLE]

TYPE
  TBuff = ARRAY[1..10] of BYTE;

VAR
  B1,B2 : TBuff;
  I     : INTEGER;

BEGIN

  FillChar( B1, SizeOf( B1 ), 4 );
  FillChar( B2, SizeOf( B2 ), 4 );

  B2[7] := 49;  { Force MisCompare }

  I := CompareSmaller( B1, B2, SizeOf( TBuff ) );

  { I = -1  - MisCompare, 1st Buffer Smaller! }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  CompareBufByte(        Var Buff;
                                     Count     : WORD;
                                     B         : BYTE    ) : WORD;

[PARAMETERS]

Buff        VAR Address of Buffer (Generic Type)
Count       Number of bytes in each buffer (Max = $FFFE byte)
B           Comparison byte

[RETURNS]

Index of First Miscompared byte in Buffer, 0 if Buffer all data matches
Compare Byte

[DESCRIPTION]

Compares a buffer with a byte value to determine whether or not all bytes
in that buffer are the same as the comparison byte.  Returns Zero if all
buffer data bytes match the compare byte, otherwise returns the index
into the buffer of the miscompare.

[SEE-ALSO]

FastCompare
Compare
CompareSmaller

[EXAMPLE]

TYPE
  TBuffer = ARRAY[1..512] of BYTE;

VAR
  B : TBuffer;
  C : BYTE;
  W : WORD;

BEGIN

  { COMPARE MATCH }

  FillChar( B, 512, #30 );
  C := #30;
  W := CompareBufByte( B, 512, C );

  { W will now equal 0 (Comparison Match) }

  { COMPARE MISMATCH }

  B[274] := $FF;  { Just to make sure Doesn't Compare }
  W := CompareBufByte( B, 512, C );

  { W will now Equal 274 (Index of Mismatch) }

END.

TYPE
  TBuff = ARRAY[1..10] of BYTE;

VAR
  Buf : TBuff;
  B   : BYTE;
  W   : WORD;

BEGIN

  FillChar( Bur, SizeOf( TBuff ), 4 );
  Buf[7] := 49;  { Force MisCompare! }

  W := CompareSmaller( Buf, SizeOf( TBuff ), $04 );

  { W = 7  - MisCompare Index! }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  CompareBufWord(        Var Buff;
                                     Count     : WORD;
                                     W         : WORD    ) : WORD;

[PARAMETERS]

Buff        VAR Address of Buffer (Generic Type)
Count       Number of Words in each buffer (Max of $FFFE bytes)
W           2-Byte Comparison Value

[RETURNS]

Word Index of First Miscompared Word in Buffer, 0 if Buffer all data
matches the 2-Byte Compare Value (a Word)

[DESCRIPTION]

Compares a buffer with a 2-Byte value (a WORD) to determine whether or
not all Words in that buffer are the same as the comparison byte.
Returns Zero if all buffer data words match the compare word, otherwise
returns the Word Index into the buffer of the miscompare.

[SEE-ALSO]

FastCompare
Compare
CompareSmaller

[EXAMPLE]

TYPE
  TBuffer = ARRAY[1..256] of BYTE;

VAR
  B : TBuffer;
  C : BYTE;
  W : WORD;

BEGIN

  { COMPARE MATCH }

  FillChar( B, SizeOf( TBuffer ), #30 );
  C := #30;
  W := CompareBufByte( B, 256, C );

  { W will now equal 0 (Comparison Match) }

  { COMPARE MISMATCH }

  B[137] := $FF;  { Just to make sure Doesn't Compare }
  W := CompareBufByte( B, 256, C );

  { W will now Equal 137 (Index of Mismatch) }

END.


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LookupByte(                 InByte   : BYTE;
                                      Count    : WORD;
                                  Var LTable;
                                  Var OutByte  : BYTE              ) : BOOLEAN;

[PARAMETERS]

InByte      Source Byte to look up in Table
Count       Number of entries in the lookup table
LTable      Address of the lookup table
OutByte     Byte indentified by source byte in table

[RETURNS]

TRUE if the source byte was found in the table, FALSE if one was not.

[DESCRIPTION]

This function allow a quick lookup of a 2-byte record (the first byte
being the lookup key and the 2nd byte being the data to find).  The
actual record is set up as in the example below.  It is an array of
translation records (see example).

You pass in a prepared lookup table and ask it to find the data
associated with a specific "key".  This can be useful for such actions
as translation tables for error codes, etc.

[SEE-ALSO]

LookupWord

[EXAMPLE]

Type
  TTableRec = RECORD
    Key  : BYTE;
    Data : BYTE;
  END;

  TTable = Array[1..6] of TTableRec;

VAR
  T : TTable;
  B : BYTE;

BEGIN

  T[1].Key :=  0;   T[1].Data := 14;
  T[2].Key :=  3;   T[2].Data := 12;
  T[3].Key :=  7;   T[3].Data := 54;
  T[4].Key := 12;   T[4].Data :=  2;
  T[5].Key := 14;   T[5].Data :=  7;
  T[6].Key := 15;   T[6].Data :=  9;

  If LookupByte( 12, 6, @T, B ) Then
    WriteLn( 'Item Found in Table.  Data=',B )
  Else
    WriteLn( 'Item NOT Found in Table.' );

  {------------------------------------------------}
  { Output would be "Item Found in Table.  Data=2" }
  {------------------------------------------------}

END.


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LookupWord(                 InWord   : WORD;
                                      Count    : WORD;
                                  Var LTable;
                                  Var OutWord  : WORD              ) : BOOLEAN;

[PARAMETERS]

InWord      Source word to look up in table
Count       Number of entries in the lookup table
LTable      Address of the lookup table
OutWord     Word indentified by source byte in table

[RETURNS]

TRUE if the source word was found in the table, FALSE if one was not.

[DESCRIPTION]

This function allow a quick lookup of a 4-byte record (the first word
being the lookup key and the second word being the data to find).  The
actual record is set up as in the example below.  It is an array of
translation records (see example).

You pass in a prepared lookup table and ask it to find the data
associated with a specific "key".  This can be useful for such actions
as translation tables for error codes, etc.

[SEE-ALSO]

LookupWord

[EXAMPLE]

TYPE
  TTableRec = RECORD
    Key  : WORD;
    Data : WORD;
  END;

  TTable = Array[1..6] of TTableRec;

VAR
  T : TTable;
  W : WORD;

BEGIN

  T[1].Key :=  0;   T[1].Data := 14;
  T[2].Key :=  3;   T[2].Data := 12;
  T[3].Key :=  7;   T[3].Data := 54;
  T[4].Key := 12;   T[4].Data :=  2;
  T[5].Key := 14;   T[5].Data :=  7;
  T[6].Key := 15;   T[6].Data :=  9;

  If LookupByte( 12, 6, @T, B ) Then
    WriteLn( 'Item Found in Table.  Data=',B )
  Else
    WriteLn( 'Item NOT Found in Table.' );

  {------------------------------------------------}
  { Output would be "Item Found in Table.  Data=2" }
  {------------------------------------------------}

END.


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure SwapBuffers(           Var Buf1;
                                 Var Buf2;
                                     Count     : WORD    );

[PARAMETERS]

Buf1        VAR Address of First buffer of data
Buf2        VAR Address of Second buffer of data
Count       Number of bytes to swap

[RETURNS]

(None)

[DESCRIPTION]

Swaps a given number of bytes between two types/untyped buffers.

[SEE-ALSO]

[EXAMPLE]

TYPE
  TBuff = ARRAY[1..10] of BYTE;

VAR
  B1,B2 : TBuff;

BEGIN

  FillChar( B1, SizeOf( B1 ), 1 );
  FillChar( B2, SizeOf( B2 ), 2 );

  SwapBuffers( B1,B2, SizeOf( TBuff ) );

  { B1 now filled with 2's and B2 filled with 1's }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure SwapWords(             Var A,
                                     B         : WORD    );

[PARAMETERS]

A           VAR First word to swap
B           VAR Second word to swap

[RETURNS]

(None)

[DESCRIPTION]

Executes a bufferless two-word swap

[SEE-ALSO]

SwapInts
SwapBytes

[EXAMPLE]

VAR
  W1,W2 : WORD;

BEGIN

  W1 := 5;
  W2 := 3;

  SwapWords( W1, W2 );

  { W1 = 3, W2 = 5 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure SwapInts(              Var A,
                                     B         : INTEGER );

[PARAMETERS]

A           VAR First integer to swap
B           VAR Second integer to swap

[RETURNS]

(None)

[DESCRIPTION]

Executes a bufferless two-integer swap

[SEE-ALSO]

SwapWords
SwapBytes

[EXAMPLE]

VAR
  I1,I2 : INTEGER;

BEGIN

  I1 :=  5;
  I2 := -3;

  SwapInts( I1, I2 );

  { I1 = -3; I2 = 5 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure SwapBytes(             Var A,
                                     B         : BYTE    );

[PARAMETERS]

A           VAR First byte to swap
B           VAR Second byte to swap

[RETURNS]

(None)

[DESCRIPTION]

Executes a Bufferless 2-Byte swap

[SEE-ALSO]

SwapWords
SwapInts

[EXAMPLE]

VAR
  B1,B2 : BYTE;

BEGIN

  B1 := 5;
  B2 := 3;

  SwapBytes( B1, B2 );

  { B1 = 3, B2 = 5 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  GreaterInt(                A,
                                     B         : INTEGER ) : INTEGER;

[PARAMETERS]

A           First integer to compare
B           Second integer to compare

[RETURNS]

Greater of the two provided integer

[DESCRIPTION]

Compares two integer and returns the greater.

[SEE-ALSO]

GreaterWord
GreaterLong
LesserInt
LesserWord
LesserLong

[EXAMPLE]

VAR
  I1,I2,I3 : INTEGER;

BEGIN

  I1 :=  5;
  I2 := -3;

  I3 := GreaterInt( I1, I2 );

  { I3 = 5 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  GreaterWord(               A,
                                     B         : WORD    ) : WORD;

[PARAMETERS]

A           First word to compare
B           Second word to compare

[RETURNS]

Greater of the two provided words

[DESCRIPTION]

Compares two words and returns the greater.

[SEE-ALSO]

GreaterInt
GreaterLong
LesserInt
LesserWord
LesserLong

[EXAMPLE]

VAR
  W1,W2,W3 : INTEGER;

BEGIN

  W1 := 5;
  W2 := 3;

  W3 := GreaterWord( W1, W2 );

  { W3 = 5 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  GreaterLong(               A,
                                     B         : LONGINT ) : LONGINT;

[PARAMETERS]

A           First longint (signed double word) to compare
B           Second longint to compare

[RETURNS]

Greater of the two provided longints

[DESCRIPTION]

Compares two longints (signed double words) and returns the greater

[SEE-ALSO]

GreaterInt
GreaterWord
LesserInt
LesserWord
LesserLong

[EXAMPLE]

VAR
  L1,L2,L3 : INTEGER;

BEGIN

  L1 := 5;
  L2 := 3;

  L3 := GreaterLong( L1, L2 );

  { L3 = 5 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LesserInt(                 A,
                                     B         : INTEGER ) : INTEGER;

[PARAMETERS]

A           First integer to compare
B           Second integer to compare

[RETURNS]

Lesser of the two integers

[DESCRIPTION]

Compares two integers and returns the lesser

[SEE-ALSO]

GreaterInt
GreaterWord
GreaterLong
LesserWord
LesserLong

[EXAMPLE]

VAR
  I1,I2,I3 : INTEGER;

BEGIN

  I1 :=  5;
  I2 := -3;

  I3 := LesserLong( I1, I2 );

  { I3 = -3 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LesserWord(                A,
                                     B         : WORD    ) : WORD;

[PARAMETERS]

A           First word to compare
B           Second word to compare

[RETURNS]

Lesser of the two words

[DESCRIPTION]

Compares two words and returns the lesser

[SEE-ALSO]

GreaterInt
GreaterWord
GreaterLong
LesserInt
LesserLong

[EXAMPLE]

VAR
  W1,W2,W3 : WORD;

BEGIN

  W1 := 5;
  W2 := 3;

  W3 := LesserWord( W1, W2 );

  { W3 = 3 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LesserLong(                A,
                                     B         : LONGINT ) : LONGINT;

[PARAMETERS]

A           First longint (double word) to compare
B           Second longint to compare

[RETURNS]

Lesser of the two longints

[DESCRIPTION]

Compares two longints (signed double words) and returns the lesser

[SEE-ALSO]

GreaterInt
GreaterWord
GreaterLong
LesserInt
LesserWord

[EXAMPLE]

VAR
  L1,L2,L3 : INTEGER;

BEGIN

  L1 := 5;
  L2 := 3;

  L3 := LesserLong( L1, L2 );

  { L3 = 3 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure FillWord(              Var Buf;
                                     Count     : WORD;
                                     Value     : WORD    );
[PARAMETERS]

Buf         VAR Address of untyped Buffer to fill
Count       Number of Words to Fill
Value       Word Value to fill Buffer with

[RETURNS]

Function : None
(Var     : [Buf] Buffer fill with Value)

[DESCRIPTION]

Takes an Untyped Buffer and fills it with a given Word Value "Value"
up to the number of Words given in "Count".  This is the same thing
as PASCAL's FillChar except it allows you to fill with 2-Byte Patterns
instead.

WARNING: Make sure Count Represents Buffer Size in Terms of 2-Byte
Words rather than simply the number of bytes of the Buffer.  Otherwise
this may result in a buffer overrun, potentially overwritting other
data in memory.

[SEE-ALSO]

FillLong

[EXAMPLE]

TYPE
  TBuff = ARRAY[1..12] of BYTE;

VAR
  B : TBuff;

BEGIN

  FillWord( B, SizeOf( B ) DIV 2, $1234 );

  { Entire Buffer (B) Filled with 2-Byte Value $1234 }

END;


──────────────────────────────────────────────────────────────────────────────


Procedure FillLong(              Var Buf;
                                     Count     : WORD;
                                     Value     : LONGINT );
[PARAMETERS]

Buf         VAR Address of untyped Buffer to fill
Count       Number of Words to Fill
Value       Longint Value to fill Buffer with

[RETURNS]

Function : None
(Var     : [Buf] Buffer fill with Value)

[DESCRIPTION]

Takes an Untyped Buffer and fills it with a given Longint Value "Value"
up to the number of Longints given in "Count".  This is the same thing
as PASCAL's FillChar except it allows you to fill with 4-Byte Patterns
instead.

WARNING: Make sure Count Represents Buffer Size in Terms of 4-Byte
Words rather than simply the number of bytes of the Buffer.  Otherwise
this may result in a buffer overrun, potentially overwritting other
data in memory.

[SEE-ALSO]

FillWord

[EXAMPLE]

TYPE
  TBuff = ARRAY[1..12] of BYTE;

VAR
  B : TBuff;

BEGIN

  FillWord( B, SizeOf( B ) DIV 4, $12345678 );

  { Entire Buffer (B) Filled with 4-Byte Value $12345678 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure RebootMachine(             WarmBoot : BOOLEAN );

[PARAMETERS]

WarmBoot   TRUE to warmboot machine,
           FALSE to coldboot (do post and memory checks)


[RETURNS]

(None)

[DESCRIPTION]

Reboots the system.


  ++++++++++++++++++++++++++++++++++++++++++++++++
  +                                              +
  + NOTE:                                        +
  +                                              +
  + On AT and compatible machines, the keyboard  +
  + controller is wired to the CPUs reboot line. +
  + Here we tell the keyboard controller to      +
  + wiggle the reboot line.  This is the same    +
  + thing that the code at $FFFF:0 does.         +
  + We talk to the keyboard controller directly  +
  + because you would otherwise need to make     +
  + DPMI calls when in protected/windows mode.   +
  +                                              +
  ++++++++++++++++++++++++++++++++++++++++++++++++

[SEE-ALSO]

[EXAMPLE]


BEGIN

  WriteLn( 'Ready to Reboot your System.' );
  WriteLn( 'Press "W" to WarmBoot, otherwise will Coldboot' );

  RebootMachine( UpCase( ReadKey ) = 'W' );

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure SetKeyRate(                Delay     : BYTE;
                                     Rate      : BYTE    );

[PARAMETERS]

Delay       Delay value to set keyboard repeat to
Rate        Rate at which keys are read after delay period

[RETURNS]

(None)

[DESCRIPTION]

Sets the Keyboard typematic Rate and Delay times.

Delay       Delay value to set keyboard repeat to (this is a table)
                00h =  250ms  02h =  750ms
                01h =  500ms  03h = 1000ms

Rate        Rate at which keys are read after delay period (this is a table)
               Value Table is as such:
                00h = 30.0ms  08h = 15.0ms  10h =  7.5ms  18h =  3.7ms
                01h = 26.7ms  09h = 13.3ms  11h =  6.7ms  19h =  3.3ms
                02h = 24.0ms  0Ah = 12.0ms  12h =  6.0ms  1Ah =  3.0ms
                03h = 21.8ms  0Bh = 10.9ms  13h =  5.5ms  1Bh =  2.7ms
                04h = 20.0ms  0Ch = 10.0ms  14h =  5.0ms  1Ch =  2.5ms
                05h = 18.5ms  0Dh =  9.2ms  15h =  4.6ms  1Dh =  2.3ms
                06h = 17.1ms  0Eh =  8.6ms  16h =  4.3ms  1Eh =  2.1ms
                07h = 16.0ms  0Fh =  8.0ms  17h =  4.0ms  1Fh =  2.0ms
[SEE-ALSO]

SetKeyFast

[EXAMPLE]

VAR
  ch : CHAR;

BEGIN

  WriteLn( 'Setting Fastest Key Rate & Least Delay' );
  SetkeyRate( $00, $00 );

  WriteLn( 'Test by typing any key, <ENTER> to go to next test.' );
  REPEAT
    ch := ReadKey;
    Write( ch );
  UNTIL ch = #13;

  WriteLn( 'Setting Slowest Key Rate & Greatest Delay' );
  SetKeyRate( $03, $1F );

  WriteLn( 'Test by typing any key, <ESC> to quit test.' );
  REPEAT
    ch := ReadKey;
    Write( ch );
  UNTIL ch = #27;

  WriteLn( 'Resetting keyboard to Default Rate & Delay' );
  SetKeyRate( $01, $04 );

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure SetKeyFast;

[PARAMETERS]

(None)

[RETURNS]

(None)

[DESCRIPTION]

Sets the keyboard delay and rate to its maximum value

[SEE-ALSO]

SetKeyRate

[EXAMPLE]

VAR
  ch : CHAR;

BEGIN

  WriteLn( 'Test Current Keyboard Setting' );
  WriteLn( 'Test by typing any key, <ENTER> to for Fastest Speed.' );
  REPEAT
    ch := ReadKey;
    Write( ch );
  UNTIL ch = #13;

  WriteLn( 'Setting Fastest Key Rate & Least Delay' );
  SetkeyFast;
  WriteLn( 'Test by typing any key, <ESC> to go to quit.' );
  REPEAT
    ch := ReadKey;
    Write( ch );
  UNTIL ch = #27;

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure PurgeKbdBuf;

[PARAMETERS]

(None)

[RETURNS]

(None)

[DESCRIPTION]

Flushes the Keyboard type-ahead buffer.  Keyboard buffer is now empty
and like nothing has been pressed.

[SEE-ALSO]

[EXAMPLE]

VAR
  ch : CHAR;

BEGIN

  WriteLn( 'Hold down a Key until Keyboard Buffer is Full (Beeps)' );
  WriteLn( 'and Keep Holding that Key.' );

  While NOT KeyPressed Do;

  Delay(2000);

  WriteLn( 'Purging Key Buffer.  And Accepting Keystokes... <ESC>=Quit' );
  PurgeKbdBuf;

  REPEAT
    ch := ReadKey;
    Write( ch );
  UNTIL ch = #27;

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure KeyboardOff;

[PARAMETERS]

(None)

[RETURNS]

(None)

[DESCRIPTION]

Turns off keyboard access to the system

[SEE-ALSO]

KeyboardOn

[EXAMPLE]

VAR
  ch : CHAR;

BEGIN

  WriteLn( 'Type any Key to demonstrate Keyboard Active.' );
  WriteLn( 'Press <ENTER> when Ready for Test.' );
  REPEAT
    ch := ReadKey;
    Write( ch );
  UNTIL ch = #13;

  KeyboardOff;
  WriteLn( 'Keyboard is Now INACTIVE for 5 seconds.');
  WriteLn( 'Try to Press a Key.' );
  Delay( 5000 );

  KeyboardOn;

  WriteLn( 'Keyboard is ACTIVE again. Press any key.  <ESC>=Quit' )
  REPEAT
    ch := Readkey;
    Write( ch );
  UNTIL ch = #27;

  WriteLn( 'End of Test' );

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure KeyboardOn;

[PARAMETERS]

(None)

[RETURNS]

(None)

[DESCRIPTION]

Turms on keyboard access to the system

[SEE-ALSO]

KeyboardOff

[EXAMPLE]

VAR
  ch : CHAR;

BEGIN

  WriteLn( 'Type any Key to demonstrate Keyboard Active.' );
  WriteLn( 'Press <ENTER> when Ready for Test.' );
  REPEAT
    ch := ReadKey;
    Write( ch );
  UNTIL ch = #13;

  KeyboardOff;
  WriteLn( 'Keyboard is Now INACTIVE for 5 seconds.');
  WriteLn( 'Try to Press a Key.' );
  Delay( 5000 );

  KeyboardOn;

  WriteLn( 'Keyboard is ACTIVE again. Press any key.  <ESC>=Quit' )
  REPEAT
    ch := Readkey;
    Write( ch );
  UNTIL ch = #27;

  WriteLn( 'End of Test' );

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure CRC16Char(           Var Ch          : CHAR;
                               Var Result      : WORD );

[PARAMETERS]

Ch          VAR Address of Source Byte to CRC
Result      VAR Returned 16-Bit CRC Checksum on Source Byte

[RETURNS]

Function : None
(Var     : [Result] Returned 16-Bit CRC Checksum on Source Byte)

[DESCRIPTION]

[SEE-ALSO]

CRC16String
CRC16Buffer
CRC32Char
CRC32String
CRC32Buffer

[EXAMPLE]

VAR
  Ch    : CHAR;
  CRC16 : WORD;

BEGIN

  Ch := 'A';

  CRC16Char( Ch, CRC16 );

  { CRC16 = $0041 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure CRC16Buffer(         Var Buf;
                                   Count       : WORD;
                               Var Result      : WORD );

[PARAMETERS]

Buf         VAR Address of untyped Data Buffer to CRC
Count       Number of bytes in Data Buffer
Result      VAR 16-bit CRC totals on Data Buffer

[RETURNS]

Function : None
(Var     : [Result] 16-bit CRC on the Buffer)

[DESCRIPTION]

[SEE-ALSO]

CRC16Char
CRC16String
CRC32Char
CRC32String
CRC32Buffer

[EXAMPLE]

TYPE
  TBuff = ARRAY[1..10] of BYTE;

VAR
  B     : TBuff;
  CRC16 : WORD;

BEGIN

  FillChar( B, SizeOf( B ), $04 );
  CRC16 := 0;

  CRC16Buffer( B, SizeOf( B ), CRC16 );

  { CRC16 = $43D3 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure CRC32Char(           Var Ch          : CHAR;
                               Var Result      : LONGINT );

[PARAMETERS]

Ch          VAR Address of Source Byte to CRC
Result      VAR Returned 32-Bit CRC Checksum on Source Byte

[RETURNS]

Function : None
(Var     : [Result] 32-Bit CRC Checksum on Source Byte)

[DESCRIPTION]

[SEE-ALSO]

CRC16Char
CRC16String
CRC16Buffer
CRC32String
CRC32Buffer

[EXAMPLE]

VAR
  Ch    : CHAR;
  CRC32 : LONGINT;

BEGIN

  Ch := 'A';

  CRC32Char( Ch, CRC32 );

  { CRC32 = $01DB7106 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure CRC32Buffer(         Var Buf;
                                   Count       : WORD;
                               Var Result      : LONGINT );

[PARAMETERS]

[RETURNS]

[DESCRIPTION]

[SEE-ALSO]

CRC16Char
CRC16String
CRC16Buffer
CRC32Char
CRC32String

[EXAMPLE]

TYPE
  TBuff = ARRAY[1..10] of BYTE;

VAR
  B     : TBuff;
  CRC32 : LONGINT;

BEGIN

  FillChar( B, SizeOf( B ), $04 );
  CRC32 := 0;

  CRC32Buffer( B, SizeOf( B ), CRC32 );

  { CRC32 = $1716C742 }

END;

──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure Sort(               Var Buf;
                                  Index         : LONGINT;
                                  Count         : LONGINT;
                                  SortProc      : PSortProc;
                                  Params        : STRING        );

[PARAMETERS]

Buf         Untyped pointer to the base of the data element array.
Index       Element within array to begin sorting.
Count       Number of elements to sort in the table.
SortProc    Pointer to a comparison function.
Params      Parameter string with specific sorting information.

[RETURNS]

Buf         Sorted buffer

[DESCRIPTION]

Sorts a table of data elements using the Heapsort algorithm.  A user-supplied
comparison function is allowed for maximum flexability - but not required for
ShortInt, Byte, Integer, Word, LongInt, String, PString, PChar, and Real
types, which are all auto-formatted.

For "user-supplied" types, SortProc should be a function which Sort uses for
element comparisons.  Sort will pass two pointers that address elements in
the table being sorted.  The function should follow the TSortProc template,
where a -1 should be returned if the first parameter is less that the second,
0 if the two parameters are equal, or +1 if the first parameter is greater
than the second.

The parameter string is a string containing a list of specific sorting
instructions to use.  The commands within the Params string must be comma
delimited with no spaces.

Parameter substrings are as follows:

  ElementType=$    Where $ is the type of element within the table.
                   Default is word type.

                   Allowed ElementTypes, preset ElementSize, and
                   kind of element for each include:

                   SHORTINT - 1    Ordinals
                   BYTE     - 1    Ordinals
                   INTEGER  - 2    Ordinals
                   WORD     - 2    Ordinals
                   LONGINT  - 4    Ordinals
                   STRING   - 256  Fixed-length (see below)
                   PSTRING  - 4    Pointers for Variant-length
                   PCHAR    - 4    Pointers for Variant-length
                   REAL     - 6    Floating-points

                   If the actual ElementSize for a String type is less
                   than 256 (ie. STRING[80]), use ElementSize afterwards to
                   reset to the lesser size.

                   If you are using an external compare function, then the
                   ElementType parameter should not be used.

  'ElementSize=#'  Where # is the size of each element within the table.
                   Default is 2, the size of a word.  Note that only User
                   types are not precasted in size, and must have this
                   parameter included.

[SEE-ALSO]

(None)

[EXAMPLE]

Var

  Table : Array[1..5] of STRING;

BEGIN

  Table[1] := 'ALPHA';
  Table[2] := 'CHARLIE';
  Table[3] := 'ECHO';
  Table[4] := 'DELTA';
  Table[5] := 'BRAVO';

  Sort( Table, 1, 5, NIL, 'ElementType=STRING' );

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  SoundexPack(               S         : STRING  ) : WORD;

[PARAMETERS]

S           Text string (one text word) to Soundex Encode and pack

[RETURNS]

Packed (as WORD) Soundex Code for string

[DESCRIPTION]

Soundex Encodes a text string and packs it as word value.
A Soundex Code is an AlphaNumeric Code derived from the pronounciation
of a text word.  It's standard format is the first letter of the
original word along with a numbering system designed to encompass
sounds of similar pronounciation.  The result is that the Soundex Code
for a word is the same as a Soundex for a word which sounds the same.
(ie. "There", "Their", and "They're" would all have the same Soundex
Code).  This resulting code is further compressed from 4 bytes downto
the space of a single binary word (2 bytes).  Uses SoundexUnPack to
revert to it's standard Soundex Format.  This Packed Code may be used
just as you would the standard Soundex Code in all operations and uses.
In fact, it is recommended to be used in this format for saving of
record storage space as well as simplicity of comparison tests.

[SEE-ALSO]

SoundexUnPack
SoundexStr

[EXAMPLE]

VAR
  W1,W2 : WORD;

BEGIN

  W1 := SoundexPack( 'Jonson' );
  W2 := SoundexPack( 'Johnsonn' );

  { Both W1 and W2 contain the value 10765 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  SoundexUnPack(             W         : WORD    ) : STRING;

[PARAMETERS]

W           Word representing Packed Soundex Code to be unpacked

[RETURNS]

Standard Unpacked Soundex Code from Packed Code Value

[DESCRIPTION]

Unpacks a soundex code from packed code value.
A Soundex Code is an AlphaNumeric Code derived from the pronounciation
of a text word.  It's standard format is the first letter of the
original word along with a numbering system designed to encompass
sounds of similar pronounciation.  (See SoundexPack for example)  This
takes the packed 2 byte compressed Soundex Code and uncompresses it
it's standard Soundex Format as a 4 byte string Code.  It is recommended
that for operational uses, the compressed for be used for both the
savings of record storage space as well as simplicity of comparison tests.

[SEE-ALSO]

SoundexPack
SoundexStr

[EXAMPLE]

VAR
  W : WORD;
  S : STRING;

BEGIN

  W := SoundexPack( 'Jonson' );
  S := SoundexUnPack( W );

  { W = 10765, S = 'J525' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  SoundexStr(                S         : STRING  ) : STRING;

[PARAMETERS]

[RETURNS]

[DESCRIPTION]

For the rare instances when one would like to display the actual Soundex
Symbolic Code, this function will output that Symbolic Code as a string.

Use of this is more for show than actually utilizing the data, as it is
always faster and much more efficient to use a Packed Soundex Code value
for all comparison operations than to compare by Strings.

[SEE-ALSO]

SoundexPack
SoundexUnPack

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := SoundexStr( 'Jonson' );

  { S = 'J525' }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  PtrToLin(                  Ptr       : POINTER ) : LONGINT;

[PARAMETERS]

Ptr         Pointer Address to Convert to Linear Address

[RETURNS]

Linear Address associated with Pointer Address

[DESCRIPTION]

Converts a Segmented Address Pointer into a Linear Memory Address.

This is most useful for Windows or DPMI Pointer routines.
This could also be used to manipulate Pointer Math.

[SEE-ALSO]

LinToPtr

[EXAMPLE]

VAR
  P : POINTER;
  L : LONGINT;

BEGIN

  P := Ptr( $A000, $0 );
  L := PtrToLin( P );

  { L = $000A0000 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  LinToPtr(                  Lin       : LONGINT ) : POINTER;

[PARAMETERS]

Lin         Linear Memory Address

[RETURNS]

Pointer associated with same Linear Memory Address

[DESCRIPTION]

Converts a Linear Memory Address Longint into a Segmented Memory Addr
Pointer.

[SEE-ALSO]

PtrToLin

[EXAMPLE]

VAR
  P : POINTER;
  L : LONGINT;

BEGIN

  L := $000A0000;
  P := LinToPtr( L );

  { P = $A000:0000 }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  PtrAdd(                    OrigPtr   : POINTER;
                                     AddOfs    : LONGINT ) : POINTER;

[PARAMETERS]

OrigPtr     Source Pointer to work with
AddOfs      Pointer Offset to Add

[RETURNS]

New Pointer from the above pointer math

[DESCRIPTION]

This function will take the provided Source Pointer and Add to it the
Offset Address "AddOfs" to come up with another Pointer Address.  This
is math at the Pointer Level and comes in very useful with routines
emulating C Style Pointer operations.

[SEE-ALSO]

PtrSub

[EXAMPLE]

VAR
  T,P : POINTER;
  Len : INTEGER;

BEGIN

  T   := NewString( 300, 'This is a Test' + #0 );
  { T is now a "C"-Type String }

  P   := T;
  Len := 0;

  While ( P <> #0) Do
  BEGIN
    Inc( Len );
    P := PtrAdd( P, 1 );
  END;

  { Len now equals the length of the AsciiZ string }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  PtrSub(                    OrigPtr   : POINTER;
                                     SubOfs    : LONGINT ) : POINTER;

[PARAMETERS]

OrigPtr     Source Pointer to work with
SubOfs      Pointer Offset to Subtract

[RETURNS]

New Pointer from the above pointer math

[DESCRIPTION]

This function will take the provided Source Pointer and Subtract from
it's address the Offset "SubOfs" to produce another pointer.  This is
basically math at the Pointer Level and can be very useful when used
much like C Pointer routines

Suggest that this may be more useful moving Pointer Indexes into
DataBases.

[SEE-ALSO]

PtrAdd

[EXAMPLE]


VAR
  P   : POINTER;
  Len : INTEGER;

BEGIN

  P   := NewString( 300, 'This is a Test'+#0 );
  { P is now a "C"-Type String }

  Len := 0;

  While ( P <> #0) Do
  BEGIN
    Inc( Len );
    P := PtrAdd( P, 1 );
  END;

  P := PtrSub( P, Len );

  {------------------------------------------------------}
  { "Len" now equals the length of the AsciiZ string     }
  { while "P" is returned to the original string address }
  {------------------------------------------------------}


  {-------------------------------------------------}
  { GRANTED THIS IS NOT AN EXAMPLE OF OPTIMAL USAGE }
  { BUT IT DOES SHOW THE ACTION.                    }
  {-------------------------------------------------}

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function  NewString(                 StringLen : WORD;
                                     DefString : STRING  ) : POINTER;

[PARAMETERS]

StringLen   Maximum string length to allocate
DefString   Default new string text

[RETURNS]

Pointer to New String and data.

[DESCRIPTION]

This function allows dynamic creation of strings on the heap.  Based
upon the greater of the StringLen or the DefString Length, it will
allocate memory on the heap in which to store not only the string data
but also the size of the memory block allocated (for deallocation
purposes).  This string can now be used in functions just as you would
any other -but making sure to address the data and not just the pointer.

There are advantages in obtaining strings from Heap Memory as opposed
to the Stack, not the least of which is the fact that the Heap is larger
and more Dynamic where the Stack has to be set at Compile Time.

[SEE-ALSO]

GetHeapString
DisposeString

[EXAMPLE]

VAR
  P : POINTER;

BEGIN

  P := NewString( 'This is the String' );

  { P now points to the String Data as well as the Memory Allocations }

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Function GetHeapString(      HeapStringPtr : PString ) : STRING;

[PARAMETERS]

HeapStringPtr   String Pointer

[RETURNS]

Pascal String in Heap Memory

[DESCRIPTION]

This is the

There are advantages in obtaining strings from Heap Memory as opposed
to the Stack, not the least of which is the fact that the Heap is larger
and more Dynamic where the Stack has to be set at Compile Time.

[SEE-ALSO]

NewString
DisposeString

[EXAMPLE]

VAR
  S : STRING;

BEGIN

  S := GetHeapString( NewString( 'This is the String' ) );

  {--------------------------------------------------------------------}
  { S now contains "This is the String" from the Dynamically allocated }
  { from the Heap while the String Pointer itself also includes the    }
  { Memory Allocation associated with this String Pointer              }
  {--------------------------------------------------------------------}

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure DisposeString(             PrevNewString : POINTER );

[PARAMETERS]

PrevNewString   Existing String pointer created by NewString

[RETURNS]

(None)

[DESCRIPTION]

This is the complementary function to NewString.  It will take the
NewString string pointer and deallocate it from the heap.  It should
be noted that all the information about the allocated memory size is
already contained with the string pointer data, thus deallocation is
completely invisible to the user.

[SEE-ALSO]

NewString
GetHeapString

[EXAMPLE]

VAR
  P : POINTER;

BEGIN

  P := NewString( 'This is the String' );
  { P now points to the String Data as well as the Memory Allocations }

  DisposeString( P );

  {-----------------------------------}
  { P now is an unassigned pointer,   }
  { all memory associated with it has }
  { been deallocated                  }
  {-----------------------------------}

END;


──────────────────────────────────────────────────────────────────────────────


[FUNCTION]

Procedure FarCall(          Proc          : POINTER );

[PARAMETERS]

Proc        Far Pointer to Procedure to Call

[RETURNS]

(None)

[DESCRIPTION]

Jumps to the Far Pointer and executes the Procedure.

NOTE: Caller must be sure to declare his Procedures to be called
as Far Procedures as shown in the Example below.

[SEE-ALSO]

(None)

[EXAMPLE]

Procedure MyRoutine; Far
BEGIN
  WriteLn( 'Something to Do.');
END;

BEGIN

  FarCall( @MyRoutine );

END.